Get Organization Usage Breakdown

Read ranked organization usage by member, workspace, workflow, model, BYOK provider, or source. Requires organization administrator access and Usage Monitoring. Omitted usage is summarized in other. BYOK ranks tokens; other dimensions rank cost. More than 10,000 underlying groups returns 413; narrow the window or workspace. Workspace API keys return 403; use a personal API key or scoped OAuth token.

OAuth scope: api:read.

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

Authorization

X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one under Settings, then API Keys. Operations that reject workspace keys say so in their own description.

In: header

Path Parameters

organizationId*string

Organization identifier.

Length1 <= length

Query Parameters

preset?string

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"
Value in"current-period" | "previous-period" | "7d" | "30d" | "custom"
startDate?string

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

Match^(?:(?:\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])))$
Formatdate
endDate?string

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

Match^(?:(?:\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])))$
Formatdate
timezone?string

IANA timezone for calendar boundaries; defaults to UTC.

Default"UTC"
Length1 <= length
workspaceId?string

Restrict usage to one workspace owned by the organization.

Length1 <= length <= 128
dimension*string

Usage grouping dimension.

Value in"member" | "workspace" | "workflow" | "model" | "byok" | "source"
limit?integer

Maximum ranked groups to return. Remaining usage is summarized in other. Must be a whole number from 1 to 100. Defaults to 50.

Default50
Range1 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://www.sim.ai/api/v2/organizations/string/usage/breakdown?dimension=member" \  -H "X-API-Key: YOUR_API_KEY"
{
  "data": {
    "dimension": "member",
    "rows": [
      {
        "id": "user-123",
        "label": "Example Member",
        "credits": 200,
        "events": 1,
        "share": 1
      }
    ],
    "other": {
      "credits": 0,
      "events": 0,
      "rowCount": 0,
      "tokens": 0
    },
    "totalCredits": 200
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient workspace permissions",
    "details": {
      "code": "INSUFFICIENT_WORKSPACE_ROLE"
    }
  }
}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found"
  }
}
{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body is too large"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API rate limit exceeded",
    "details": {
      "retryAfter": "2026-01-01T00:00:30.000Z"
    }
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
GETGet Organization Member Credit LimitGETGet Organization Usage Summary