Skip to main content
Fetch the per-request billing events that Frontier Gateway records for your inference traffic. Each event carries token counts, the calling group’s external entity ID, and the API key prefix that made the request. These are the same API_BILLING_USAGE events that billing webhooks deliver: use this endpoint to pull them on demand instead of running a webhook receiver. For webhook delivery, signature verification, and retry semantics, see Billing events.

​
Authentication

​
string
required
Workspace API key with management scope, passed as Authorization: Bearer $BASETEN_API_KEY (Api-Key is also accepted). Federated gateway keys are rejected: this is an operator endpoint, not an inference credential.

​
Query parameters

​
string
required
Inclusive start of the fetch window, in ISO 8601 UTC, for example 2026-08-01T00:00:00Z. Required unless you pass cursor to continue a previous page.
​
string
Exclusive end of the window, in ISO 8601 UTC. Defaults to the current time, minus a short ingestion holdback, so events from roughly the last minute aren’t returned yet. The window is evaluated once: the cursor pins it, so pagination continues inside the same window.
​
integer
Page size. Default 100, maximum 1000.
​
array of strings
Filter to events charged against these API key prefixes, repeated once per prefix, for example api_keys=sky_abc12345&api_keys=sky_def67890. Omit to return events for all keys.
​
array of strings
Filter to events for these external entity IDs (the group’s metadata.external_entity_id), repeated once per ID. Omit to return events for all groups.
​
string
Pagination cursor from the previous response’s pagination.cursor. When present, all other parameters are ignored: the cursor carries the window, page size, and filters from the original request. Omit on the first call.
Events come back in ascending timestamp order, with ties broken by idempotencyKey. Fetched events don’t include the request’s requestMetadata passthrough. If you need it, use billing webhooks instead.

​
Errors

Authorizations

​
Authorization
string
header
required

Send Authorization: Bearer <api_key>. The legacy Authorization: Api-Key <api_key> scheme is also accepted.

Query Parameters

​
start_time
string<date-time> | null

Inclusive start (ISO 8601, UTC). Required without a cursor.

​
end_time
string<date-time> | null

Exclusive end (ISO 8601, UTC). Defaults to now.

​
limit
integer | null

Max events. Default 100, max 1000.

Required range: 1 <= x <= 1000
​
api_keys
string[]

Return only events for these API key prefixes, repeated once per prefix.

​
external_entity_ids
string[]

Return only events for these external entity IDs, repeated once per ID.

​
cursor
string | null

Next-page cursor. Other parameters are ignored.

Response

200 - application/json
​
items
GatewayEventV1 · object[]
required

Items in this page.

​
pagination
PaginationResponseV1 · object
required

Pagination metadata for the page.