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

List workspace usage

The workspace’s usage rows, one per measurement, joined with their cost. Rows are ordered by id, which is assigned before a row commits, so a row can appear behind a cursor already passed: walking this listing forward can miss rows. To account usage, read the usage report instead.

GET/v1/workspaces/{workspace_id}/usage
Authorization
AuthorizationBearer token · headerrequired
Path parameters
workspace_idstring<uuid>required
Workspace id
Query parameters
limitinteger<int64>
min 1 · max 200
afterstring<uuid>
Rows past this id in `order`'s direction: a page's `next_cursor`.
beforestring<uuid>
Rows just before this id, still in `order`'s direction: a page's `prev_cursor`.
orderOrderParam
Newest first when omitted.
Allowed:ascdesc
starting_atstring<date-time>
Only rows accounted at or after this instant.
ending_atstring<date-time>
Only rows accounted before this instant.
metadataobject
Only rows whose metadata holds each pair, matched exactly: `metadata[tenant_id]=t_123`. Several pairs must all hold.
Responses
200One page, newest recorded first unless order=asc.
itemsUsageEventBody[]required
Show properties
Array of UsageEventBody
accounted_atstring<date-time>required
The instant the row counts toward, which `starting_at` and `ending_at` filter on: `occurred_at`, unless the row was recorded after the usage report had already finalized that instant.
adjustsstring<uuid> | nullrequired
The event this one corrects.
billingUsageBillingBodyrequired
How a row was priced. `rated`: a charge landed with it, which `cost` names. `byok`: a call through the workspace's own model provider, which is never charged. `unrated`: a charge was due but no rate priced it. Stable vocabulary for v1: adding a value requires a new API version.
Allowed:ratedbyokunrated
costinteger<int64> | nullrequired
Hundred-millionths of a credit, as `balance`. Absent for a byok call or a platform one nothing priced.
idstring<uuid>required
metadataobjectrequired
The metadata of the session the row was spent in, copied when it was recorded.
occurred_atstring<date-time>required
recorded_atstring<date-time>required
resourceUsageResourceBodyrequired
What an event measured; `kind` names the shape.
Show properties
One of:
object
kindstringrequired
Allowed:llm_tokens
modelstringrequired
model_call_idstring<uuid>required
model_provider_idstring<uuid>required
provider_ownerModelProviderOwnerBodyrequired
Who owns the provider: Subako publishes a `platform` provider with its own catalog, while a `workspace` provider is one you bound with your own key.
Allowed:platformworkspace
run_idstring<uuid>required
session_idstring<uuid>required
usageModelUsageBodyrequired
Show properties
One of:
object
formatstringrequired
Allowed:anthropic
usageAnthropicUsageBodyrequired
Show properties
cache_creation_input_tokensinteger<int64>required
cache_read_input_tokensinteger<int64>required
input_tokensinteger<int64>required
output_tokensinteger<int64>required
object
formatstringrequired
Allowed:openai_responses
usageOpenaiResponsesUsageBodyrequired
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
object
duration_msinteger<int64>required
harnessstringrequired
kindstringrequired
Allowed:harness_runtime
run_idstring<uuid>required
session_idstring<uuid>required
object
classstringrequired
duration_msinteger<int64>required
kindstringrequired
Allowed:sandbox_runtime
session_idstring<uuid>required
object
bytesinteger<int64>required
duration_msinteger<int64>required
kindstringrequired
Allowed:storage
session_idstring<uuid>required
subjectStorageSubjectBodyrequired
What a storage event held.
Allowed:archivevolume
object
elapsed_msinteger<int64>required
grantstringrequired
The grant the call went through, as the agent's config names it.
kindstringrequired
Allowed:function_runtime
run_idstring<uuid>required
session_idstring<uuid>required
toolstringrequired
object
bytesinteger<int64>required
grantstring | null
kindstringrequired
Allowed:volume_write
run_idstring<uuid> | null
session_idstring<uuid>required
toolstring | null
workspace_idstring<uuid>required
next_cursorstring<uuid> | nullrequired
Pass back as `after` for the next page; `null` on the last page.
prev_cursorstring<uuid> | nullrequired
Pass back as `before` for the previous page; `null` on the first page.
400Bad limit, cursor, order, filter, or path parameter.
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
Try it
Server
Authorization
Parameters
Request
curl -X GET "https://api.us.cloud.subako.ai/v1/workspaces/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
{
  "items": [
    {
      "accounted_at": "2019-08-24T14:15:22Z",
      "adjusts": "60135a0a-8dab-43fa-be89-97697a4b4be7",
      "billing": "rated",
      "cost": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "occurred_at": "2019-08-24T14:15:22Z",
      "recorded_at": "2019-08-24T14:15:22Z",
      "resource": {
        "kind": "llm_tokens",
        "model": "string",
        "model_call_id": "9b27d4e1-b224-4b1a-b5e9-e99e5c49f3ea",
        "model_provider_id": "e8dd39c4-1070-4c00-8ab5-c345bdef77c9",
        "provider_owner": "platform",
        "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
        "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
        "usage": {
          "format": "anthropic",
          "usage": {
            "cache_creation_input_tokens": 0,
            "cache_read_input_tokens": 0,
            "input_tokens": 0,
            "output_tokens": 0
          }
        }
      },
      "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
    }
  ],
  "next_cursor": "a7ec8888-a9c3-4732-a281-9a08510f220b",
  "prev_cursor": "2ffdd032-1f96-48c2-8179-571201598694"
}