End User Costs API

Get cost trend for a specific end-user

Returns time-series cost data with adaptive granularity for the specified end-user. Call it with a GET request to /end-user-costs/{externalId}/trend, authenticated with a restricted API key and the "costs:read" scope.

GET https://api.bearlumen.com/v1/end-user-costs/{externalId}/trend

Returns time-series cost data with adaptive granularity for the specified end-user. Granularity is selected from the date range: 30 days or less returns daily points, 31-90 days weekly, longer ranges monthly. The response granularity field reports which was used. Periods with no events are omitted from dataPoints (not returned as zero-cost points); fill gaps client-side if your chart requires a continuous series. 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 costs:read scope.

Parameters

Name	In	Type	Required	Description
`externalId`	path	`string`	Yes	End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).

Response example

Success response (200):

{
  "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01",
  "granularity": "daily",
  "series": [
    {
      "data_points": [
        {
          "cost": "522.3",
          "date": "2026-05-16T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "336.48",
          "date": "2026-05-18T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "241.06",
          "date": "2026-05-20T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "236.04",
          "date": "2026-05-23T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "381.68",
          "date": "2026-05-25T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "190.84",
          "date": "2026-05-27T00:00:00.000Z",
          "event_count": 1
        }
      ],
      "key": "user_fixture_a",
      "label": "user_fixture_a"
    }
  ]
}

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 data. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.
`401`	Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY.
`403`	API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry.
`404`	End user not found. The identifier must match the user_id value sent on at least one ingested usage event.
`429`	Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).

Rate limits and retries

Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).