> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List gateway events

> Fetch Frontier Gateway billing events over a time window. Cursor-paginated, with optional filters by API key prefix and external entity ID.

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](/frontier-gateway/billing-events).

### Authentication

<ParamField header="Authorization" type="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.
</ParamField>

### Query parameters

<ParamField query="start_time" type="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.
</ParamField>

<ParamField query="end_time" type="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.
</ParamField>

<ParamField query="limit" type="integer">
  Page size. Default 100, maximum 1000.
</ParamField>

<ParamField query="api_keys" type="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.
</ParamField>

<ParamField query="external_entity_ids" type="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.
</ParamField>

<ParamField query="cursor" type="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.
</ParamField>

### Response

Events come back in ascending timestamp order, with ties broken by `idempotencyKey`.

<ResponseField name="items" type="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](/reference/gateway/groups/create-a-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](/frontier-gateway/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](/reference/gateway/billing-webhooks) instead.
</ResponseField>

<ResponseField name="pagination" type="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.
</ResponseField>

### Errors

| Status            | Meaning                                                                                                                        |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `400 Bad Request` | Missing `start_time` without a `cursor`, `end_time` not after `start_time`, `limit` outside 1 to 1000, or an invalid `cursor`. |
| `403 Forbidden`   | Workspace isn't onboarded to Frontier Gateway, the caller doesn't have management scope, or a federated gateway key was used.  |

<RequestExample>
  ```bash curl theme={"system"}
  curl --request GET \
    --url "https://api.baseten.co/v1/gateway/events?start_time=2026-08-01T00:00:00Z&end_time=2026-08-02T00:00:00Z" \
    --header "Authorization: Api-Key $BASETEN_API_KEY"
  ```

  ```bash filtered by group theme={"system"}
  curl --request GET \
    --url "https://api.baseten.co/v1/gateway/events?start_time=2026-08-01T00:00:00Z&external_entity_ids=cust_42" \
    --header "Authorization: Api-Key $BASETEN_API_KEY"
  ```

  ```bash next page theme={"system"}
  curl --request GET \
    --url "https://api.baseten.co/v1/gateway/events?cursor=aVd2Yk54T2d2V0dFWE13R1l4R2k5UVE=" \
    --header "Authorization: Api-Key $BASETEN_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "items": [
      {
        "type": "API_BILLING_USAGE",
        "idempotencyKey": "01J9X7Y0Z3K4M5N6P7Q8R9S0T1",
        "timestamp": "2025-07-07T23:40:35.905Z",
        "requestId": "5e4a8c1a-2b3c-4d5e-9f0a-1b2c3d4e5f6a",
        "modelSlug": "your-org/your-model",
        "externalEntityId": "cust_42",
        "apiKeyPrefix": "sky_abcdefgh",
        "tokens": {
          "inputTokens": 2500,
          "outputTokens": 384,
          "cachedInputTokens": 2000
        }
      }
    ],
    "pagination": {
      "has_more": false,
      "cursor": null
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml get /v1/gateway/events
openapi: 3.1.0
info:
  description: REST API for management of Baseten resources
  title: Baseten management API
  version: 1.0.0
servers:
  - url: https://api.baseten.co
security:
  - BearerAuth: []
paths:
  /v1/gateway/events:
    get:
      summary: Lists gateway events
      parameters:
        - name: start_time
          in: query
          required: false
          description: Inclusive start (ISO 8601, UTC). Required without a cursor.
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            default: null
            title: Start Time
        - name: end_time
          in: query
          required: false
          description: Exclusive end (ISO 8601, UTC). Defaults to now.
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: 'null'
            default: null
            title: End Time
        - name: limit
          in: query
          required: false
          description: Max events. Default 100, max 1000.
          schema:
            anyOf:
              - maximum: 1000
                minimum: 1
                type: integer
              - type: 'null'
            default: null
            title: Limit
        - name: api_keys
          in: query
          required: false
          description: >-
            Return only events for these API key prefixes, repeated once per
            prefix.
          schema:
            items:
              type: string
            title: Api Keys
            type: array
        - name: external_entity_ids
          in: query
          required: false
          description: >-
            Return only events for these external entity IDs, repeated once per
            ID.
          schema:
            items:
              type: string
            title: External Entity Ids
            type: array
        - name: cursor
          in: query
          required: false
          description: Next-page cursor. Other parameters are ignored.
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
            title: Cursor
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayEventsResponseV1'
      x-codeSamples:
        - lang: bash
          source: |
            curl --request GET \
            --url https://api.baseten.co/v1/gateway/events \
            --header "Authorization: Bearer $BASETEN_API_KEY"
        - lang: python
          source: |-
            import requests
            import os
            API_KEY = os.environ.get("BASETEN_API_KEY", "<YOUR_API_KEY>")
            url = "https://api.baseten.co/v1/gateway/events"

            headers = {"Authorization": f"Bearer {API_KEY}"}

            response = requests.request(
                "GET",
                url,
                headers=headers,
                params={'start_time': None, 'end_time': None, 'limit': None, 'cursor': None}
            )

            print(response.text)
components:
  schemas:
    GatewayEventsResponseV1:
      properties:
        items:
          description: Items in this page.
          items:
            $ref: '#/components/schemas/GatewayEventV1'
          title: Items
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationResponseV1'
          description: Pagination metadata for the page.
      required:
        - items
        - pagination
      title: GatewayEventsResponseV1
      type: object
    GatewayEventV1:
      properties:
        type:
          default: API_BILLING_USAGE
          description: Event type.
          title: Type
          type: string
        idempotencyKey:
          description: Deduplication key.
          title: Idempotencykey
          type: string
        timestamp:
          description: Billing event time (ISO 8601, UTC).
          title: Timestamp
          type: string
        requestId:
          description: Inference request ID.
          title: Requestid
          type: string
        modelSlug:
          description: Served model.
          title: Modelslug
          type: string
        externalEntityId:
          description: Calling group's external ID.
          title: Externalentityid
          type: string
        apiKeyPrefix:
          description: API key prefix.
          title: Apikeyprefix
          type: string
        tokens:
          $ref: '#/components/schemas/GatewayEventTokensV1'
      required:
        - idempotencyKey
        - timestamp
        - requestId
        - modelSlug
        - externalEntityId
        - apiKeyPrefix
        - tokens
      title: GatewayEventV1
      type: object
    PaginationResponseV1:
      properties:
        has_more:
          description: Whether more items exist after this page.
          title: Has More
          type: boolean
        cursor:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Opaque cursor to pass into the next request. Null when there is no
            next page.
          title: Cursor
      required:
        - has_more
      title: PaginationResponseV1
      type: object
    GatewayEventTokensV1:
      properties:
        inputTokens:
          description: Cached and uncached input tokens.
          title: Inputtokens
          type: integer
        outputTokens:
          description: Output tokens.
          title: Outputtokens
          type: integer
        cachedInputTokens:
          description: Cached input tokens.
          title: Cachedinputtokens
          type: integer
      required:
        - inputTokens
        - outputTokens
        - cachedInputTokens
      title: GatewayEventTokensV1
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send `Authorization: Bearer <api_key>`. The legacy `Authorization:
        Api-Key <api_key>` scheme is also accepted.

````