Skip to content
Subako Docs
English
English日本語Not translated
Esc
↑↓navigate↵open⌘Jpreview

Get the workspace's usage report

Usage summed per bucket of the span and per value of each group_by dimension, split by kind and by how it was priced: rated usage a charge landed with, byok calls through the workspace’s own model provider, and unrated usage no rate priced. Usage counts toward the instant it is accounted at, which is when it occurred unless it was recorded after that instant was final. A row whose ending_at is at or before finalized_before never changes again, so re-reading only the rows after it, and taking the difference from what was read before, accounts every row exactly once.

GET/v1/workspaces/{workspace_id}/usage-report
Authorization
AuthorizationBearer token · headerrequired
Path parameters
workspace_idstring<uuid>required
Workspace id
Query parameters
starting_atstring<date-time>required
The span's start, inclusive: usage accounted at or after it.
ending_atstring<date-time>required
The span's end, exclusive. A span covers at most 31 days at `all` or `1d` and at most 7 days at `1h`.
bucket_widthBucketWidthParam
How finely to cut the span: `all`, the default, makes it one bucket; `1d` and `1h` cut it per UTC day or hour, and need `starting_at` and `ending_at` on those boundaries.
Allowed:all1d1h
group_bystring[]
What to sum separately for each value of, repeated in the order rows sort by: `kind`, `model_provider_id`, `model`, `session_id`, or `metadata.<key>`. At most 8. Omitted, each bucket is one row.
limitinteger<int64>
Rows on the page. Defaults to 100.
min 1 · max 1000
afterstring
The previous page's `next_cursor`. The other parameters must be the ones that page was read with.
metadataobject
Only rows whose metadata holds each pair, matched exactly: `metadata[tenant_id]=t_123`. Several pairs must all hold.
Responses
200One page of the report.
finalized_beforestring<date-time> | nullrequired
A row whose `ending_at` is at or before this instant is final and never changes again; a later one may still grow. Null until any usage is final.
itemsUsageReportRowBody[]required
Ordered by `starting_at`, then by each `group_by` value in turn, bytewise, with no value last. A combination with no usage has no row.
Show properties
Array of UsageReportRowBody
ending_atstring<date-time>required
kindstring
The usage kind, such as `llm_tokens` or `storage`. An open vocabulary: a kind Subako starts measuring later arrives under its own name, so a client keeps a value it does not know rather than rejecting the row.
metadataobject
One entry per `metadata.<key>` grouped by.
modelstring | null
model_provider_idstring<uuid> | null
session_idstring<uuid> | null
starting_atstring<date-time>required
usageUsageSummaryBodyrequired
What a row's usage came to, kind by kind. A kind with no usage is absent, and a kind added later arrives as a field of its own, which a client that does not know it ignores.
Show properties
costinteger<int64>required
Hundred-millionths of a credit: every `rated` cost below, summed.
function_runtimeRuntimeSummaryBody
Run time by how it was priced. A class with none is absent.
Show properties
ratedRatedDurationBody
Show properties
costinteger<int64>required
Hundred-millionths of a credit.
duration_msinteger<int64>required
unratedDurationBody
Time a charge was due for but no rate priced.
Show properties
duration_msinteger<int64>required
harness_runtimeRuntimeSummaryBody
Run time by how it was priced. A class with none is absent.
Show properties
ratedRatedDurationBody
Show properties
costinteger<int64>required
Hundred-millionths of a credit.
duration_msinteger<int64>required
unratedDurationBody
Time a charge was due for but no rate priced.
Show properties
duration_msinteger<int64>required
llm_tokensLlmTokensSummaryBody
Model calls by how they were priced. A class with no calls is absent.
Show properties
byokTokensBody
Calls no charge landed with.
Show properties
tokensTokenTotalsBodyrequired
Token counts summed per format, each field on its own: the formats count different things, so they are never added together. A format with no calls is absent.
Show properties
anthropicAnthropicUsageBody
Show properties
cache_creation_input_tokensinteger<int64>required
cache_read_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
openai_responsesOpenaiResponsesUsageBody
Show properties
cache_write_input_tokensinteger<int64>required
cached_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
reasoning_output_tokensinteger<int64>required
ratedRatedTokensBody
Calls a charge landed with.
Show properties
costinteger<int64>required
Hundred-millionths of a credit, across formats.
tokensTokenTotalsBodyrequired
Token counts summed per format, each field on its own: the formats count different things, so they are never added together. A format with no calls is absent.
Show properties
anthropicAnthropicUsageBody
Show properties
cache_creation_input_tokensinteger<int64>required
cache_read_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
openai_responsesOpenaiResponsesUsageBody
Show properties
cache_write_input_tokensinteger<int64>required
cached_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
reasoning_output_tokensinteger<int64>required
unratedTokensBody
Calls no charge landed with.
Show properties
tokensTokenTotalsBodyrequired
Token counts summed per format, each field on its own: the formats count different things, so they are never added together. A format with no calls is absent.
Show properties
anthropicAnthropicUsageBody
Show properties
cache_creation_input_tokensinteger<int64>required
cache_read_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
openai_responsesOpenaiResponsesUsageBody
Show properties
cache_write_input_tokensinteger<int64>required
cached_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
reasoning_output_tokensinteger<int64>required
sandbox_runtimeRuntimeSummaryBody
Run time by how it was priced. A class with none is absent.
Show properties
ratedRatedDurationBody
Show properties
costinteger<int64>required
Hundred-millionths of a credit.
duration_msinteger<int64>required
unratedDurationBody
Time a charge was due for but no rate priced.
Show properties
duration_msinteger<int64>required
storageStorageSummaryBody
Storage held, archives and volumes together, by how it was priced. A class with none is absent.
Show properties
ratedRatedStorageBody
Show properties
byte_hoursinteger<int64>required
Bytes held times hours held, rounded down.
costinteger<int64>required
Hundred-millionths of a credit.
unratedStorageBody
Storage a charge was due for but no rate priced.
Show properties
byte_hoursinteger<int64>required
Bytes held times hours held, rounded down.
volume_writeVolumeWriteSummaryBody
Bytes written to volumes by how they were priced. A class with none is absent.
Show properties
ratedRatedBytesBody
Show properties
bytesinteger<int64>required
costinteger<int64>required
Hundred-millionths of a credit.
unratedBytesBody
Bytes a charge was due for but no rate priced.
Show properties
bytesinteger<int64>required
next_cursorstring | nullrequired
Pass as `after`, with the same other parameters, for the next page; null on the last.
400A parameter missing, malformed, or out of bounds; a span longer than its bucket width allows or off its boundaries; a cursor from another query; or a report that ran too long, which a narrower span, grouping, or filter avoids.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
401Missing, malformed, or invalid bearer token.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
403Caller lacks usage.read.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
404No such workspace, or the caller cannot see it. An API key sees only its own workspace.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
429The organization is already running two reports, or this server's report connections are all busy.
errorErrorDetailrequired
What went wrong: a `code` to branch on and a `message` to show. The message is written for a person and may change; the code will not.
Show properties
codeErrorCoderequired
The machine-readable half of an error response, and the field a client branches on. Closed: every error carries exactly one of these.
Allowed:unauthorizedforbiddennot_foundinvalid_requestconflictclient_outdatedprecondition_failedtoo_many_requestsinternal
messagestringrequired
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.us.cloud.subako.ai/v1/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage-report?starting_at=2019-08-24T14%3A15%3A22Z&ending_at=2019-08-24T14%3A15%3A22Z" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "finalized_before": "2019-08-24T14:15:22Z",
  "items": [
    {
      "ending_at": "2019-08-24T14:15:22Z",
      "kind": "string",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "model": "string",
      "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9",
      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
      "starting_at": "2019-08-24T14:15:22Z",
      "usage": {
        "cost": 0,
        "function_runtime": {
          "rated": {
            "cost": 0,
            "duration_ms": 0
          },
          "unrated": {
            "duration_ms": 0
          }
        },
        "harness_runtime": {
          "rated": {
            "cost": 0,
            "duration_ms": 0
          },
          "unrated": {
            "duration_ms": 0
          }
        },
        "llm_tokens": {
          "byok": {
            "tokens": {
              "anthropic": {
                "cache_creation_input_tokens": 0,
                "cache_read_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0
              },
              "openai_responses": {
                "cache_write_input_tokens": 0,
                "cached_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0,
                "reasoning_output_tokens": 0
              }
            }
          },
          "rated": {
            "cost": 0,
            "tokens": {
              "anthropic": {
                "cache_creation_input_tokens": 0,
                "cache_read_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0
              },
              "openai_responses": {
                "cache_write_input_tokens": 0,
                "cached_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0,
                "reasoning_output_tokens": 0
              }
            }
          },
          "unrated": {
            "tokens": {
              "anthropic": {
                "cache_creation_input_tokens": 0,
                "cache_read_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0
              },
              "openai_responses": {
                "cache_write_input_tokens": 0,
                "cached_input_tokens": 0,
                "input_tokens": 0,
                "output_tokens": 0,
                "reasoning_output_tokens": 0
              }
            }
          }
        },
        "sandbox_runtime": {
          "rated": {
            "cost": 0,
            "duration_ms": 0
          },
          "unrated": {
            "duration_ms": 0
          }
        },
        "storage": {
          "rated": {
            "byte_hours": 0,
            "cost": 0
          },
          "unrated": {
            "byte_hours": 0
          }
        },
        "volume_write": {
          "rated": {
            "bytes": 0,
            "cost": 0
          },
          "unrated": {
            "bytes": 0
          }
        }
      }
    }
  ],
  "next_cursor": "string"
}