Skip to content
Try for free
On this page

Organizations

List organization usage events

List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. `sim-chat` covers both chat surfaces. Per-event rounding can yield `credits: 0` with `hasCost: true`. Workspace API keys return `403`; use a personal API key or scoped OAuth token. OAuth scope: `api:read`.

GET/api/v2/organizations/{organizationId}/usage/events

List usage events, including zero-cost activity. Requires organization Admin access and Usage Monitoring. Defaults to 30 days. Cursors retain the initial reporting window; keep filters and sort unchanged while paging. sim-chat covers both chat surfaces. Per-event rounding can yield credits: 0 with hasCost: true. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Path parameters

organizationIdstringRequired

Organization identifier.

minLength
1

Query parameters

presetstring

Reporting window. Custom requires startDate and endDate and is capped at 92 days; other presets reject those bounds. Resolved billing windows are capped at 366 days.

default
30d
enum
["current-period","previous-period","7d","30d","custom"]
startDatestring

First calendar date included, in the selected timezone. Requires preset=custom.

format
date
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
endDatestring

Last calendar date included, in the selected timezone. Requires preset=custom.

format
date
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
timezonestring

IANA timezone for calendar boundaries; defaults to UTC.

default
UTC
minLength
1
sourcestring

Restrict events to one product surface.

enum
["workflow","wand","sim-chat","mcp_copilot","mothership_block","knowledge-base","voice-input","enrichment","voice-output","api-tool"]
limitinteger

Maximum usage events per page. Must be a whole number from 1 to 100. Defaults to 50.

default
50
minimum
1
maximum
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1
sortBystring

Field used to sort the result.

default
createdAt
enum
["createdAt"]
sortOrderstring

Sort direction.

default
desc
enum
["asc","desc"]

Responses

200

A page of usage events, including zero-cost activity.

object

A page of usage events, including zero-cost activity.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject
7 fields
idstringRequired

Usage event identifier.

createdAtstringRequired

When the usage event was recorded.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
sourcestringRequired

Product surface that recorded the usage.

enum
["workflow","wand","sim-chat","mcp_copilot","mothership_block","knowledge-base","voice-input","enrichment","voice-output","api-tool"]
descriptionstringRequired

Usage event description, such as a model name.

workflowNamevalueRequired

Workflow name, or null for non-workflow usage or a deleted workflow.

Schema details

Any of

Option 1string
Option 2null
creditsnumberRequired

Credits consumed by this event, rounded to whole credits.

hasCostbooleanRequired

Whether the event consumed credits before rounding, including sub-credit usage.

Additional properties are not allowed.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Response example 1

json
{
  "data": [
    {
      "id": "event-123",
      "createdAt": "2026-06-01T09:00:00.000Z",
      "source": "sim-chat",
      "description": "Model usage",
      "workflowName": null,
      "credits": 200,
      "hasCost": true
    }
  ],
  "nextCursor": null
}

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit