Usage & analytics API

The usage API exposes three read-only endpoints for querying token consumption, cost estimates, and request counts recorded by the Arbitex Gateway.

Stats (/api/usage/stats) returns pre-aggregated totals and breakdowns, suitable for dashboards and cost-allocation reports. Records (/api/usage/records) returns per-request detail — one row per gateway request — suitable for audit trails, debugging, and fine-grained chargebacks. Org plan usage (/api/orgs/{org_id}/usage) returns the current-period utilization against the plan limit for a specific organization.

Access scoping is enforced server-side. Regular users receive only their own data regardless of what filter parameters are passed. Platform admins receive data across all users. Org admins can retrieve plan usage for their own organization via the /api/orgs/{org_id}/usage endpoint.

Authentication

All three endpoints require a Bearer token in the Authorization header:

Authorization: Bearer arb_live_...

Token types accepted: API keys and session JWTs both work. For automated collection jobs (dashboards, cost exporters), use an API key generated under a service account with appropriate role. See API Keys for key lifecycle management.

Access scoping by role:

Role	`/api/usage/stats`	`/api/usage/records`	`/api/orgs/{org_id}/usage`
Regular user	Own data only	Own records only	Not accessible
Org admin	Own data only	Own records only	Own org only
Platform admin	All users	All users	Any org

The user_id filter on /api/usage/records is silently ignored for non-admin callers — passing another user’s ID returns an empty result set, not an error.

GET /api/usage/stats

Returns aggregated token, cost, and request-count totals for the authenticated user (or all users for admins). Includes two breakdowns: by model and by calendar day.

GET https://api.arbitex.ai/api/usage/stats
Authorization: Bearer arb_live_...

Query parameters

Parameter	Type	Required	Description
`date_from`	string (YYYY-MM-DD)	No	Start date, inclusive. Interpreted as UTC midnight.
`date_to`	string (YYYY-MM-DD)	No	End date, inclusive. Interpreted as UTC midnight of the following day.
`model_id`	string	No	Filter to a single model ID. Must match exactly.

Omitting date_from and date_to returns all-time aggregates. See Time-range filtering for details.

Response schema

UsageStatsResponse

Field	Type	Description
`total_input_tokens`	integer	Sum of all input tokens across matching records
`total_output_tokens`	integer	Sum of all output tokens across matching records
`total_cost`	float	Estimated total cost in USD
`request_count`	integer	Total number of matching requests
`by_model`	array of `ModelBreakdown`	Per-model breakdown, ordered by `request_count` descending
`by_day`	array of `DailyBreakdown`	Per-calendar-day breakdown, ordered by date ascending

ModelBreakdown

Field	Type	Description
`model_id`	string	Model identifier as submitted in the request
`provider`	string or null	Provider name, if known
`input_tokens`	integer	Input tokens for this model
`output_tokens`	integer	Output tokens for this model
`cost`	float	Estimated cost in USD for this model
`request_count`	integer	Number of requests using this model

DailyBreakdown

Field	Type	Description
`date`	string (YYYY-MM-DD)	Calendar date in UTC
`input_tokens`	integer	Input tokens on this day
`output_tokens`	integer	Output tokens on this day
`cost`	float	Estimated cost in USD for this day
`request_count`	integer	Number of requests on this day

Example request

curl "https://api.arbitex.ai/api/usage/stats?date_from=2026-03-01&date_to=2026-03-09" \
  -H "Authorization: Bearer arb_live_your-api-key-here"

Example response

{
  "total_input_tokens": 1482300,
  "total_output_tokens": 284700,
  "total_cost": 4.73,
  "request_count": 2150,
  "by_model": [
    {
      "model_id": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "input_tokens": 980000,
      "output_tokens": 196000,
      "cost": 3.14,
      "request_count": 1400
    },
    {
      "model_id": "gpt-4o",
      "provider": "openai",
      "input_tokens": 502300,
      "output_tokens": 88700,
      "cost": 1.59,
      "request_count": 750
    }
  ],
  "by_day": [
    {
      "date": "2026-03-01",
      "input_tokens": 162000,
      "output_tokens": 31200,
      "cost": 0.52,
      "request_count": 238
    },
    {
      "date": "2026-03-02",
      "input_tokens": 175800,
      "output_tokens": 33600,
      "cost": 0.56,
      "request_count": 251
    }
  ]
}

GET /api/usage/records

Returns a paginated list of individual request records, one per gateway request. Each record contains the model used, token counts, cost estimate, request type, and timestamp.

GET https://api.arbitex.ai/api/usage/records
Authorization: Bearer arb_live_...

Query parameters

Parameter	Type	Required	Description
`date_from`	string (YYYY-MM-DD)	No	Start date, inclusive.
`date_to`	string (YYYY-MM-DD)	No	End date, inclusive.
`model_id`	string	No	Filter to a single model ID.
`user_id`	UUID string	No	Admin only. Filter to a specific user. Ignored for non-admin callers.
`request_type`	string	No	Filter by request type. Values from the `RequestType` enum (e.g., `chat_completion`, `completion`).
`limit`	integer	No	Page size. Range: 1–1000. Default: `100`.
`offset`	integer	No	Number of records to skip. Default: `0`.

Response schema

UsageRecordListResponse

Field	Type	Description
`records`	array of `UsageRecordResponse`	Records for this page
`total`	integer	Total matching records across all pages
`limit`	integer	Page size used for this response
`offset`	integer	Offset used for this response

Use total, limit, and offset to implement pagination: the next page starts at offset + limit. When offset + limit >= total, you have retrieved all records.

Example request

Retrieve the first 50 chat completion records for March 2026, for a specific user (admin caller):

curl "https://api.arbitex.ai/api/usage/records?date_from=2026-03-01&date_to=2026-03-09&request_type=chat_completion&user_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=50&offset=0" \
  -H "Authorization: Bearer arb_live_your-api-key-here"

Example response

{
  "records": [
    {
      "id": "urec_01HZ_AAA",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model_id": "claude-3-5-sonnet-20241022",
      "provider": "anthropic",
      "request_type": "chat_completion",
      "input_tokens": 1240,
      "output_tokens": 380,
      "cost": 0.00492,
      "created_at": "2026-03-09T11:24:03Z"
    },
    {
      "id": "urec_01HZ_BBB",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model_id": "gpt-4o",
      "provider": "openai",
      "request_type": "chat_completion",
      "input_tokens": 870,
      "output_tokens": 210,
      "cost": 0.00325,
      "created_at": "2026-03-09T11:19:47Z"
    }
  ],
  "total": 2150,
  "limit": 50,
  "offset": 0
}

GET /api/orgs/{org_id}/usage

Returns current-period plan utilization for an organization. The period is defined by the organization’s subscription billing cycle and is recomputed at request time.

GET https://api.arbitex.ai/api/orgs/{org_id}/usage
Authorization: Bearer arb_live_...

Path parameters

Parameter	Type	Description
`org_id`	UUID	The organization ID to query

Access control

This endpoint has stricter access requirements than the user-scoped usage endpoints:

Platform admins can query any org_id.
Org admins can query only their own organization. The request is authorized when the caller’s tenant_id matches org_id. Requests for a different org return 403.
Regular users cannot access this endpoint.

Response schema

OrgUsageResponse

Field	Type	Description
`org_id`	string	Organization ID
`plan_tier`	string	Active plan tier. See plan tier values below.
`request_count`	integer	Number of requests in the current period
`limit`	integer	Monthly request limit for the active plan tier
`period_start`	string (YYYY-MM-DD)	Start of the current billing period
`period_end`	string (YYYY-MM-DD)	End of the current billing period
`percentage_used`	float	`request_count / limit * 100`, rounded to two decimal places
`warning_level`	string	Threshold level reached. See warning level values below.

Plan tier values

Value	Description
`devfree_saas`	Developer free tier (SaaS)
`devpro_saas`	Developer Pro (SaaS)
`team_saas`	Team plan (SaaS)
`enterprise_saas`	Enterprise (SaaS)
`enterprise_outpost`	Enterprise with Outpost (self-hosted data plane)

Warning level values

Value	Threshold	Description
`none`	< 80 %	Usage is within normal range
`warning_80`	>= 80 %	Usage has reached 80 % of the period limit
`warning_95`	>= 95 %	Usage has reached 95 % of the period limit

The warning_level field reflects the highest threshold crossed. An org at 97 % usage returns warning_95, not warning_80.

Example request

curl "https://api.arbitex.ai/api/orgs/f47ac10b-58cc-4372-a567-0e02b2c3d479/usage" \
  -H "Authorization: Bearer arb_live_your-api-key-here"

Example response

{
  "org_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "plan_tier": "team_saas",
  "request_count": 41200,
  "limit": 50000,
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "percentage_used": 82.40,
  "warning_level": "warning_80"
}

Time-range filtering

The date_from and date_to parameters on /api/usage/stats and /api/usage/records accept dates in YYYY-MM-DD format and are interpreted as UTC boundaries.

date_from=2026-03-01 matches records with created_at >= 2026-03-01T00:00:00Z.
date_to=2026-03-09 matches records with created_at < 2026-03-10T00:00:00Z (end of day on March 9, UTC).

Both parameters are optional and independent:

`date_from`	`date_to`	Behavior
Set	Set	Returns records in the closed date range [from, to]
Set	Omitted	Returns all records from `date_from` through the most recent record
Omitted	Set	Returns all records up to and including `date_to`
Omitted	Omitted	Returns all records across all time

If date_from is later than date_to, the response returns an empty result set (zero records, zero totals) rather than an error.

Cost estimates in usage data are computed at request time based on the token counts recorded by the gateway and a per-model pricing table. Cost figures are estimates and may differ from provider invoices due to rounding, provider pricing changes, or features like prompt caching that adjust the billed token count.

Usage & analytics API

Authentication

GET /api/usage/stats

Query parameters

Response schema

Example request

Example response

GET /api/usage/records

Query parameters

Response schema

Example request

Example response

GET /api/orgs/{org_id}/usage

Path parameters

Access control

Response schema

Example request

Example response

Time-range filtering

See also