Get Billing Status

Return the current plan, billing standing, credit allowance, and storage quota. credits and storage report the payer's pooled allowances and are null unless the caller can manage that payer's billing; they are always null for a workspace API key. Billing history lives at GET /api/v2/billing/logs. Without a Stripe subscription — notably on the free plan — there is no real billing period: period is the open interval 1970-01-01 to 9999-12-31 and credits.used is lifetime consumption, not consumption since a period start.

GET/api/v2/billing/status

Authorization

apiKey
X-API-Key<token>

Your Sim API key, personal or workspace-scoped. Generate one from the Sim dashboard under Settings > API Keys. A workspace API key is not accepted everywhere: operations that act on behalf of a specific human — administrative reads, secret access, and irreversible or governance-affecting writes — always reject it, whatever role the key carries. Each such operation says so in its own description, and the rejection surfaces as 403 unless the operation conceals unauthorized resources, in which case it is reported as 404. Use a personal API key for those.

In: header

Query Parameters

workspaceId?string

Workspace whose payer should be resolved. Workspace API keys are pinned to their own workspace.

Length1 <= length

Response Body

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/billing/status"
{
  "data": {
    "workspaceId": null,
    "period": {
      "start": "2026-07-01T00:00:00.000Z",
      "end": "2026-08-01T00:00:00.000Z"
    },
    "plan": "pro",
    "status": "active",
    "credits": {
      "used": 512,
      "limit": 20000,
      "remaining": 19488
    },
    "storage": {
      "usedBytes": 5242880,
      "limitBytes": 1073741824,
      "percentUsed": 0.48828125
    }
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request is invalid."
  }
}