Usage & cost

The Arbitex Gateway records token consumption, cost estimates, and request metadata for every request it processes. Three data-plane endpoints let you read this data back programmatically: per-request records, aggregated stats, and org-level plan utilization.

All endpoints require a valid Arbitex API key. Regular users see only their own data. Platform admins see all users. Org admins can access their organization’s plan usage via /api/v1/orgs/{org_id}/usage.

For admin-only analytics (rollup history, per-model breakdowns, usage alerts, and analytics time-series), see the Admin Usage Analytics guide.

Base URL

https://api.arbitex.ai

GET /api/v1/usage/records

Returns a paginated list of individual per-request usage records. Each record corresponds to one request processed by the gateway — one row per chat completion call.

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

Query parameters

Parameter	Type	Default	Description
`date_from`	string (YYYY-MM-DD)	—	Start date, inclusive. Interpreted as UTC midnight.
`date_to`	string (YYYY-MM-DD)	—	End date, inclusive. Covers through end of day UTC.
`model_id`	string	—	Filter to a single model ID (exact match).
`user_id`	UUID	—	Admin only. Filter to a specific user. Silently ignored for non-admin callers.
`request_type`	string	—	Filter by request type. Valid values: `chat_completion`, `completion`.
`limit`	integer (1–200)	`100`	Page size.
`offset`	integer (≥ 0)	`0`	Number of records to skip for pagination.

Usage record schema

Each element in the records array has the following fields:

Field	Type	Description
`id`	string	Unique record identifier
`user_id`	UUID	Identifier of the user who made the request
`model_id`	string	Model identifier as submitted in the request (e.g., `gpt-4o`)
`provider`	string or null	Provider name (e.g., `openai`, `anthropic`). `null` if the provider could not be resolved.
`request_type`	string	Request type: `chat_completion` or `completion`
`input_tokens`	integer	Number of tokens in the prompt (input)
`output_tokens`	integer	Number of tokens in the completion (output)
`cost`	float	Estimated cost in USD based on the recorded token counts and the provider’s pricing table at the time of the request
`created_at`	datetime (ISO 8601)	UTC timestamp when the gateway processed the request

Pagination

The response envelope includes total, limit, and offset. To retrieve the next page, set offset = offset + limit. When offset + limit >= total, you have retrieved all records.

Field	Type	Description
`records`	array	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

Example

curl "https://api.arbitex.ai/api/v1/usage/records?date_from=2026-03-01&date_to=2026-03-09&request_type=chat_completion&limit=50&offset=0" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "records": [
    {
      "id": "urec_01HZ_AAA",
      "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "model_id": "claude-sonnet-4-20250514",
      "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/v1/usage/stats

Returns aggregated token consumption, cost totals, and request counts. The response includes two breakdowns: by model and by calendar day. Suitable for cost dashboards and per-model chargeback calculations.

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

Query parameters

Parameter	Type	Default	Description
`date_from`	string (YYYY-MM-DD)	—	Start date, inclusive.
`date_to`	string (YYYY-MM-DD)	—	End date, inclusive.
`model_id`	string	—	Filter to a single model ID.

Omitting both date parameters returns all-time aggregates. See Time-range semantics below.

Response schema

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	Per-model breakdown, ordered by `request_count` descending
`by_day`	array	Per-calendar-day breakdown, ordered by date ascending

by_model entry fields:

Field	Type	Description
`model_id`	string	Model identifier
`provider`	string or null	Provider name
`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

by_day entry fields:

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

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

{
  "total_input_tokens": 1482300,
  "total_output_tokens": 284700,
  "total_cost": 4.73,
  "request_count": 2150,
  "by_model": [
    {
      "model_id": "claude-sonnet-4-20250514",
      "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/v1/orgs/{org_id}/usage

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

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

Path parameters

Parameter	Type	Description
`org_id`	UUID	The organization to query

Access control

Platform admins can query any org_id.
Org admins can query only their own organization. Requests for a different org return 403.
Regular users cannot access this endpoint — returns 403.

Response schema

Field	Type	Description
`org_id`	string	Organization ID
`plan_tier`	string	Active plan tier (see values below)
`request_count`	integer	Number of requests in the current billing 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	Highest quota threshold crossed (see values below)

Plan tier values:

Value	Description
`devfree_saas`	Dev Free (SaaS)
`devpro_saas`	Dev Pro ($49/mo, SaaS)
`team_saas`	Team (SaaS)
`enterprise_saas`	Enterprise (SaaS)
`enterprise_outpost`	Enterprise with Hybrid Outpost

Warning level values:

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

The warning_level reflects the highest threshold crossed. An org at 97 % returns warning_95.

Example

curl "https://api.arbitex.ai/api/v1/orgs/f47ac10b-58cc-4372-a567-0e02b2c3d479/usage" \
  -H "Authorization: Bearer $ARBITEX_API_KEY"

{
  "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"
}

When usage hits warning_95, the gateway continues to accept requests. A 429 quota_exceeded error is returned only when request_count reaches limit. See API reference overview for rate-limit header semantics.

Time-range semantics

The date_from and date_to parameters on /api/v1/usage/stats and /api/v1/usage/records accept YYYY-MM-DD dates 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.

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

If date_from is later than date_to, the response returns an empty result set rather than an error.

Cost estimate accuracy: Cost figures are estimates derived from recorded token counts and a per-model pricing table maintained by the gateway. Actual provider invoices may differ due to rounding, prompt caching adjustments, or provider pricing changes. Do not use cost estimates as authoritative billing figures.

Usage & cost

Base URL

GET /api/v1/usage/records

Query parameters

Usage record schema

Pagination

Example

GET /api/v1/usage/stats

Query parameters

Response schema

Example

GET /api/v1/orgs/{org_id}/usage

Path parameters

Access control

Response schema

Example

Time-range semantics

See also