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: Api-Key $BASETEN_API_KEY (or Bearer; both are 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.

​
Response

Events come back in ascending timestamp order, with ties broken by idempotencyKey.
​
array
required
Billing events in this page. Each item describes one inference request through the gateway:
  • type (string): Event type discriminator. Always "API_BILLING_USAGE".
  • idempotencyKey (string): Stable identifier for the event. Deduplicate on this key: overlapping windows can return the same event more than once.
  • timestamp (string): ISO 8601 UTC timestamp of the inference request.
  • requestId (string): Per-request identifier, useful for correlating billing events with platform logs.
  • modelSlug (string): Model slug invoked, in your-org/your-model form.
  • externalEntityId (string): The metadata.external_entity_id of the group that owns the key used for the request, the same value you write when you create the group.
  • apiKeyPrefix (string): Prefix of the federated API key that made the request (the substring before the . in the full key string). See Manage groups and API keys.
  • tokens (object): Token counts for the request: inputTokens (cached and uncached prompt tokens), outputTokens (generated tokens), and cachedInputTokens (prompt tokens served from cache).
Fetched events don’t include the request’s requestMetadata passthrough. If you need it, use billing webhooks instead.
​
object
required
Pagination metadata for the page.
  • has_more (boolean): Whether more events exist in the window after this page.
  • cursor (string or null): Cursor for the next page. null on the last page.

​
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.