Billing API

Pull usage and cost data for your own workspace into your own systems, without opening the console. A billing key is a read-only credential scoped to one workspace - it can read billing data, and nothing else.

Creating a billing key

1. Open Console → Billing API keys (workspace owner only). Name it, optionally restrict it to an IP allow-list or set an expiry, then copy the key - it starts with sk-syn-bill- and is shown only once.
2. Call the endpoints below with it as a Bearer token. Revoke it at any time from the same page - revoking immediately invalidates it, and nothing else in the workspace is affected.
3. A key is tied to its creator: if they stop being the workspace owner, it stops working and answers 403 key_owner_not_authorized.

Authentication

Every call needs Authorization: Bearer sk-syn-bill-... against the base URL below. A billing key only works on these endpoints, and these endpoints only accept a billing key - any other combination returns 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

Base URL: https://synthorai.io/api/v1/billing

GET /usage - aggregated usage

GET /usage

Pre-aggregated rows bucketed by hour or day - built for invoices and dashboards. They come from the hourly rollup, plus the requests written since its last ingest, so recent buckets do not lag behind by a whole ingest cycle.

In each row, api_key_id and api_key_name appear only when group_by includes api_key, and model only when it includes model. avg_latency_ms can be null when a bucket has no latency samples.

Example Request

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - per-request rows

GET /records

One row per request, meant for incremental sync into your own database. Sync by cursor, never by time, and dedupe incoming rows by record_id - see "Avoiding time gaps" below for why.

Example Request

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - streamed export

GET /records/export

Same filters as /records, streamed as newline-delimited JSON (application/x-ndjson) - built for a large backfill instead of a paged list. Only one export can stream per workspace at a time; a second one gets 429 too_many_concurrent_requests.

Example Request

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

The last line of the stream is a _meta object:

GET /summary - preliminary statistics and anomalies

GET /summary

Totals, top models and top keys by cost, and an error rate for the range, plus an anomalies list (high_error_rate, rate_limited, data_not_final, rollup_delayed), each carrying a severity of info or warning and a human-readable message. Numbers in an unfinished range can still move - see below.

models_count and keys_count give the totals behind top_models and top_keys, which list at most the top 20 by cost. The range defaults to the 30 days before end when start is omitted.

Example Request

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - how complete the data is

GET /freshness

Returns data_complete_until, latest_recorded_at, safe_until and pipeline_lag_seconds - poll it before treating a just-fetched range as settled. safe_until is the newest recorded_at a caller can trust as complete; rows younger than that may still be arriving.

Example Request

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - what the workspace can spend now

GET /balance

Returns the workspace's current available balance - the same figure the console shows. Built for polling: every 30 to 60 seconds is plenty. It has its own rate limit, so polling it never uses up the budget of the data endpoints, and it keeps answering when the balance is zero.

Example Request

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

Example Response

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

Errors

Every error is {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

Rate limits and caps

Never returned: channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

Avoiding time gaps

Requests are written to the log asynchronously after they finish (seconds normally, longer under backlog), and the hourly rollup that /usage and /summary read from ingests in batches. The most recent hours are always a little incomplete. /usage and /summary also add the requests written since the last ingest (meta.live_tail is true); when the rollup is too far behind for that, meta.live_tail is false and recent buckets are partial.

data_complete_until is the earlier of two points: the hourly rollup's watermark minus its current pipeline lag, or the oldest request that has not yet been rolled up - minus a 30-minute safety margin, floored to the hour.

Every /usage row carries a final flag: true once its bucket ends at or before data_complete_until from /freshness. A final bucket never changes again.

• Aggregates: upsert each row into your own store by (bucket_start, api_key_id, model), and re-fetch any bucket while it is still final: false. Never derive a delta by subtracting an old total from a new one.
• Raw rows: sync by cursor, never by time. Keep next_cursor and resume from it on the next call, and dedupe incoming rows by record_id (a stable opaque id per row) in case a resumed page redelivers one. Rows younger than about 5 minutes are held back - safe_until is the newest recorded row's time minus 5 minutes - so a row still being committed can never slip past a cursor position already handed out, and nothing falls into a gap. To count requests, count distinct request_id.
• Bounded window: if you query a start/end range instead of syncing by cursor, trust it as complete only once window_final is true (it is true only when you gave an end and that end is at or before safe_until). If window_final is false, call again later with the same range, or switch to syncing by cursor. A window must start at or before safe_until; a later start answers 400 start_too_recent with a Retry-After header.

Recommended integration

• Nightly invoicing: call /usage once a day with granularity=day, and re-fetch any bucket your last run still saw as final: false.
• Per-request detail: call /records hourly with cursor set to the last next_cursor you stored, keep paging while has_more is true, and dedupe incoming rows by record_id.
• Dashboards: call /summary for the visible range instead of aggregating /records yourself - it already carries the anomalies list.

Need to mint or manage regular API keys programmatically instead of reading billing data? See Provisioning Keys.