API referenceAdmin APIUsage & spendUsage reportGet the usage report

Get the usage report

⚠️
Preview — this feature is being built; the design below is the spec.
GET https://app.syntic.ai/v1/organizations/usage_report/messages

Return requests and tokens over time in fixed buckets, grouped the way you choose. Covers every model request: chat completions, messages, batch items and model calls inside agent sessions. Empty buckets are included so charts have no gaps; a bucket is complete about 5 minutes after it ends.

For how this fits into a full workflow, see Usage report.

Headers

HeaderRequiredValue
AuthorizationYesBearer <admin key>: an Admin API key (sk_admin_...). Inference keys are refused with 403 admin_key_required. See Admin API keys.
syntic-betaYes, while in previewadmin-2026-11-01. Without it the call fails with 400 beta_required. See Versioning.

Query parameters

ParameterTypeDefaultDescription
starting_atRFC 3339 timeRequiredStart, rounded down to the bucket width.
ending_atRFC 3339 timenowExclusive end.
bucket_widthstring1d1m (last 7 days, up to 1,440 per page), 1h (last 90 days, up to 168) or 1d (all time, up to 31).
group_by[]stringmodel, workspace_id, api_key_id, endpoint, billing_source, user_id. Repeatable.
models[]stringOnly these models.
workspace_ids[]stringOnly these workspaces.
api_key_ids[]stringOnly these keys.
billing_sourcestringsubscription or api_credit.
limitinteger60, 24 or 7 by widthBuckets per page.
after_idstringNext page.
before_idstringPrevious page.

Response

200 OK, Content-Type: application/json

{
  "data": [
    {
      "starting_at": "2026-11-04T00:00:00Z",
      "ending_at": "2026-11-05T00:00:00Z",
      "results": [
        {
          "model": "Amara S1.2",
          "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
          "requests": 18204,
          "input_tokens": 41200310,
          "cached_input_tokens": 30988100,
          "output_tokens": 2410022,
          "reasoning_tokens": 0,
          "server_tool_use": {
            "web_search_requests": 412,
            "web_fetch_requests": 37,
            "code_execution_seconds": 0
          },
          "errors": 61
        }
      ]
    }
  ],
  "has_more": true,
  "first_id": "bkt_01JC6Z9Y8X7W6V5T",
  "last_id": "bkt_01JC7A0B2C4D6E8F"
}
FieldTypeDescription
results[].requestsintegerRequests that reached a model.
results[].input_tokensintegerPrompt tokens not served from cache.
results[].cached_input_tokensintegerPrompt tokens served from cache; add both for the full prompt.
results[].output_tokensintegerGenerated tokens, including reasoning.
results[].server_tool_useobjectCounts of separately billed built-in tool use.
results[].errorsintegerRequests that failed without using tokens.

Examples

curl -sS "https://app.syntic.ai/v1/organizations/usage_report/messages?starting_at=2026-11-01T00%3A00%3A00Z&bucket_width=1d&group_by%5B%5D=model&group_by%5B%5D=workspace_id" \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "syntic-beta: admin-2026-11-01"

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
400invalid_request_errorbeta_requiredThe syntic-beta header is missing.
400invalid_request_errorinvalid_time_rangestarting_at missing, after ending_at, or outside the data available for the bucket width.
400invalid_request_errorinvalid_group_byUnknown grouping dimension.
400invalid_request_errorlimit_out_of_rangelimit above the maximum for the width.
400invalid_request_errorinvalid_cursorA cursor from a different query.
401authentication_errorinvalid_api_keyThe admin key is missing, unknown, revoked or expired.
403permission_erroradmin_key_requiredAn inference key was used.
429rate_limit_errorrate_limitedToo many requests; wait for Retry-After. See Rate-limit headers.
Was this page helpful?