Usage Tracking API

Get usage events

Retrieves individual usage events recorded for the account your API key belongs to, within a date range. Call it with a GET request to /usage/events, authenticated with a restricted API key and the "usage:read" scope.

GET https://api.bearlumen.com/v1/usage/events

Retrieves individual usage events recorded for the account your API key belongs to, within a date range. Use it to confirm ingested events landed. Supports pagination and filtering by subscription and metric. Events sent via POST /usage-events appear here with eventType `ai.inference` and metricName `tokens`; quantity is total tokens (input plus output). Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.

Authentication and scopes

Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the usage:read scope.

Parameters

Name	In	Type	Required	Description
`start_date`	query	`string`	Yes	Start of the query range. ISO 8601 date or datetime (e.g. 2026-01-01 or 2026-01-01T00:00:00Z). Include an explicit UTC offset; date-only values are interpreted as UTC midnight. Must be strictly before end_date; the range may not exceed 90 days.
`end_date`	query	`string`	Yes	End of the query range. ISO 8601 date or datetime. Maximum range: 90 days.
`subscription_id`	query	`string`	No	Optional: Filter by subscription ID.
`metric_name`	query	`string`	No	Optional: Filter by metric name. Metric names are stored lowercase and matched exactly; pass lowercase values (e.g. tokens).
`limit`	query	`integer (int32)`	No	Optional: Number of events to return (default: 100, max: 1000, must be a positive integer).
`offset`	query	`integer (int32)`	No	Optional: Pagination offset (default: 0, must be zero or a positive integer).

Response example

Success response (200):

{
  "events": [
    {
      "event_timestamp": "2026-01-27T19:12:00.000Z",
      "event_type": "ai.inference",
      "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d08",
      "metadata": {
        "feature": "chat",
        "provider": "google"
      },
      "metric_name": "tokens",
      "quantity": 3122000
    },
    {
      "event_timestamp": "2026-01-22T08:53:00.000Z",
      "event_type": "ai.inference",
      "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d06",
      "metadata": {
        "agent_id": "support-triage",
        "feature": "search",
        "provider": "openai"
      },
      "metric_name": "tokens",
      "quantity": 6010000
    },
    {
      "event_timestamp": "2026-01-19T16:05:00.000Z",
      "event_type": "ai.inference",
      "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d04",
      "metadata": {
        "feature": "summarize",
        "provider": "anthropic"
      },
      "metric_name": "tokens",
      "quantity": 1626900
    },
    {
      "event_timestamp": "2026-01-15T10:30:00.000Z",
      "event_type": "ai.inference",
      "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d07",
      "metadata": {
        "feature": "chat",
        "provider": "google"
      },
      "metric_name": "tokens",
      "quantity": 3995000
    },
    {
      "event_timestamp": "2026-01-12T14:32:00.000Z",
      "event_type": "ai.inference",
      "id": "d7e6f5a4-9999-4b1c-8d2e-3f4a5b6c7d02",
      "metadata": {
        "feature": "chat",
        "provider": "openai"
      },
      "metric_name": "tokens",
      "quantity": 2773300
    }
  ],
  "limit": 5,
  "offset": 0,
  "total": 8
}

Error codes

Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.

Status	When it happens
`400`	Invalid request parameters. Check that start_date and end_date are valid ISO 8601 dates, start_date is strictly before end_date, the range does not exceed 90 days, and limit is a positive integer no greater than 1000.
`401`	Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.
`403`	Forbidden. The API key is missing the usage:read scope; create or update a key with that scope.
`404`	Subscription not found or not accessible with this API key. Check the subscription_id value.
`429`	Rate limit or plan quota exceeded. Slow down and retry after the current window resets.

Rate limits and retries

Rate limit or plan quota exceeded. Slow down and retry after the current window resets.