Platform API

Billing Accounts

Use billing account endpoints to read billing status, inspect current usage and spend, manage credit refills, configure auto-refill, and set spend controls.

Billing accounts can be prepaid or postpaid. Some endpoints, such as creating a refill or setting up auto-refill, only work for prepaid accounts.

API keys can only access the billing account attached to their organization.

Get Billing Account

GET /billing_accounts/{billing_account_id}

Returns billing account details.

Permission: api-read

Query parameters:

Parameter	Type	Default	Description
`force_refresh`	boolean	`false`	Refresh billing data before responding.
`include`	string	none	Comma-separated sections. Use `auto_refill`, `spend_controls`, or `all`.

Response:

{
  "data": {
    "id": "ba_...",
    "billing_email": "[email protected]",
    "billing_mode": "prepaid",
    "prepaid_entitlement_state": "enabled",
    "payment_method_required": false,
    "has_default_payment_method": true,
    "payment_method_description": "Visa ending in 4242",
    "credit_balance_cents": 10000,
    "balance_checked_at": "2026-01-01T00:00:00Z",
    "auto_refill": {
      "enabled": true,
      "threshold_cents": 1000,
      "recharge_to_cents": 10000
    },
    "spend_controls": {
      "billing_account_id": "ba_...",
      "prepaid_low_balance_warning": { "threshold_cents": 1000 },
      "usage_spend_warning": { "threshold_cents": 50000 },
      "usage_spend_cutoff": {
        "threshold_cents": 100000,
        "local_state": "enabled"
      }
    },
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

billing_mode is prepaid or postpaid. prepaid_entitlement_state can be disabled, enabled, provisioning_failed, payment_required, payment_failed, or action_required. Optional sections are omitted unless requested.

Get Current Usage

GET /billing_accounts/{billing_account_id}/usage/current

Returns current draft invoice usage.

Permission: api-read

Response:

{
  "data": [
    {
      "start_date": "2026-01-01",
      "end_date": "2026-01-31",
      "subtotal_cents": 1000,
      "total_applied_credits_cents": -200,
      "total_amount_cents": 800,
      "line_item_groups": [
        {
          "model": "qwen/qwen3.5-4b-free",
          "line_items": [
            {
              "description": "Input tokens",
              "quantity": 1000,
              "unit_price_cents": 0.01,
              "total_price_cents": 10,
              "credit_applied_cents": 0
            }
          ],
          "total_cents": 10
        }
      ]
    }
  ]
}

Get Usage Spend

GET /billing_accounts/{billing_account_id}/usage_spend

Returns usage spend by model over a range.

Permission: api-read

Query parameters:

Parameter	Type	Default	Description
`range`	string	`30d`	One of `30d`, `90d`, or `ytd`.

Response:

{
  "data": {
    "range_start": "2026-01-01T00:00:00Z",
    "range_end": "2026-01-31T00:00:00Z",
    "bucket_ms": 86400000,
    "models": [
      { "model": "qwen/qwen3.5-4b-free", "total_cents": 1000 }
    ],
    "buckets": [
      {
        "date": "2026-01-01",
        "t0": 1767225600000,
        "t1": 1767312000000,
        "total_cents": 100,
        "model_totals_cents": {
          "qwen/qwen3.5-4b-free": 100
        }
      }
    ]
  }
}

Get Spend Controls

GET /billing_accounts/{billing_account_id}/spend_controls

Returns spend controls.

Permission: api-read

Response:

{
  "data": {
    "billing_account_id": "ba_...",
    "prepaid_low_balance_warning": { "threshold_cents": 1000 },
    "usage_spend_warning": { "threshold_cents": 50000 },
    "usage_spend_cutoff": {
      "threshold_cents": 100000,
      "local_state": "enabled"
    }
  }
}

Each control may be null.

Set Spend Controls

PUT /billing_accounts/{billing_account_id}/spend_controls

Sets spend controls. Use null to disable a control.

Permission: api-admin

Request:

{
  "prepaid_low_balance_warning_threshold_cents": 1000,
  "usage_spend_warning_threshold_cents": 50000,
  "usage_spend_cutoff_threshold_cents": null
}

Fields:

Field	Type	Required	Description
`prepaid_low_balance_warning_threshold_cents`	integer or null	Yes	Low prepaid balance warning threshold in cents. Use `null` to disable this control.
`usage_spend_warning_threshold_cents`	integer or null	Yes	Usage spend warning threshold in cents. Use `null` to disable this control.
`usage_spend_cutoff_threshold_cents`	integer or null	Yes	Usage spend cutoff threshold in cents. Use `null` to disable this control.

Response:

{
  "data": {
    "billing_account_id": "ba_...",
    "prepaid_low_balance_warning": { "threshold_cents": 1000 },
    "usage_spend_warning": { "threshold_cents": 50000 },
    "usage_spend_cutoff": null
  }
}

List Refills

GET /billing_accounts/{billing_account_id}/refills

Lists credit refills.

Permission: api-read

Query parameters:

Parameter	Type	Default	Description
`limit`	integer	`20`	Maximum refills to return.

Response:

{
  "data": [
    {
      "id": "refill_...",
      "billing_account_id": "ba_...",
      "created_by_user": null,
      "amount_in_cents": 10000,
      "status": "succeeded",
      "error_message": null,
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ]
}

status is processing, succeeded, failed, action_required, or timed_out.

Get Refill

GET /billing_accounts/{billing_account_id}/refills/{refill_id}

Returns one credit refill.

Permission: api-read

Response:

{
  "data": {
    "id": "refill_...",
    "billing_account_id": "ba_...",
    "created_by_user": null,
    "amount_in_cents": 10000,
    "status": "succeeded",
    "error_message": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

Create Refill

POST /billing_accounts/{billing_account_id}/refill

Adds refill-based credit to the billing account and charges the current payment method.

Permission: api-admin

Request:

{
  "amount_in_cents": 10000
}

Fields:

Field	Type	Required	Description
`amount_in_cents`	integer	Yes	Refill amount in cents. Must be between `1000` and `50000`.

Response:

{
  "data": {
    "id": "refill_...",
    "billing_account_id": "ba_...",
    "created_by_user": null,
    "amount_in_cents": 10000,
    "status": "processing",
    "error_message": null,
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-01T00:00:00Z"
  }
}

Set Auto-Refill

PUT /billing_accounts/{billing_account_id}/auto_refill

Enables or updates auto-refill.

Permission: api-admin

Request:

{
  "threshold_cents": 1000,
  "recharge_to_cents": 10000
}

Fields:

Field	Type	Required	Description
`threshold_cents`	integer	Yes	Balance threshold in cents that triggers auto-refill.
`recharge_to_cents`	integer	Yes	Target balance in cents after auto-refill. Must be at least `1000` cents higher than `threshold_cents`.

Response:

{
  "data": {
    "enabled": true,
    "threshold_cents": 1000,
    "recharge_to_cents": 10000,
    "idempotency_key": "..."
  }
}

Disable Auto-Refill

DELETE /billing_accounts/{billing_account_id}/auto_refill

Disables auto-refill.

Permission: api-admin

Response:

{
  "data": {
    "enabled": false,
    "threshold_cents": null,
    "recharge_to_cents": null,
    "idempotency_key": "..."
  }
}

Errors

All endpoints can return:

{
  "error": {
    "message": "resource not found"
  }
}

Common statuses:

Status	Code	When
`400`	none	Invalid JSON, unsupported `range`, invalid spend-control threshold, or invalid refill/auto-refill amount.
`401`	none	Authentication failed.
`403`	`insufficient_api_key_permissions`	API key does not have the required permission.
`404`	none	Billing account, refill, or API-key organization billing account scope was not found.
`409`	billing-specific code	Billing provider conflict.
`500`	none	Internal error.

Audit Log