Usage Events API
Ingest a batch of usage events
Accepts an array of 1 to 100 usage events for cost calculation. Call it with a POST request to /usage-events/batch, authenticated with a restricted API key and the "usage:write" scope.
Accepts an array of 1 to 100 usage events for cost calculation. Each event is processed independently (partial success). A rejected item may be caused by validation failure, plan event quota exhaustion, or an unexpected processing error. The batch request itself returns 202 even when every item is rejected; plan quota exhaustion never produces a batch-level 429 and instead appears as per-item rejections, so inspect results[].status and the accepted/failed counters. Accepted events are queued for cost calculation and appear in the cost and attribution analytics endpoints once processing completes, typically shortly after ingestion. This endpoint requires HMAC request signing (X-Signature and X-Timestamp headers) in addition to your API key, and retries are safe because events are deduplicated by their idempotency_key. See the Request signing (HMAC) and Idempotency sections of this reference for the full details. **Flagged events:** status "accepted_flagged" means the event was accepted and will be processed, but needs attention. Causes: timestamp more than 24 hours old, timestamp more than 1 minute in the future, plan event quota soft limit reached, or (when no cost_override is supplied) no rate card configured for the model, in which case cost cannot be calculated until a rate card exists. flag_reason states the specific cause. When your plan quota passes its soft limit, batch items are accepted with status "accepted_flagged" and a flag_reason naming the limit; the X-BearLumen-Usage-Warning header is emitted only by the single-event endpoint. 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:write scope. It also requires HMAC request signing (the X-Signature and X-Timestamp headers) in addition to your API key.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
x-signature | header | string | No | HMAC signature of this request in the form v1={hex}; see HMAC signing above. Requests without a valid signature are rejected with 401. |
x-timestamp | header | string | No | Unix timestamp (in seconds) used in the signed payload; timestamps more than 5 minutes from server time are rejected with 401. |
Response fields
Fields returned in the 202 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.
| Field | Type | Description |
|---|---|---|
results | object[] | Per-event results. |
index | number (double) | Index of the event in the batch. |
event_id | string optional | Internal event ID (if accepted). |
status | accepted | accepted_flagged | rejected | Acceptance status. 'accepted_flagged' means accepted but needs attention (see flag causes on the endpoint description); 'rejected' means the event was not recorded and the error field states why. |
message | string | Human-readable message. |
error | string optional | Error details (if rejected). |
accepted | number (double) | Total events accepted. |
failed | number (double) | Total events rejected. Rejections can be caused by validation failure, plan event quota exhaustion, or an unexpected processing error; inspect results[].error for the cause of each. |
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 (for example an empty batch or more than 100 events). error.message names the failing field and the constraint to satisfy before retrying. |
401 | Authentication failed. Check your Authorization: Bearer API key and the X-Signature and X-Timestamp headers. API key failures return the standard error envelope; HMAC signature verification failures return a flat { "error": string, "code": string } body instead. |
403 | Insufficient permissions. Use an API key that has the usage:write scope. |
429 | API rate limit exceeded. Slow down and retry after the current window resets. Plan event quota exhaustion on this endpoint never returns a batch-level 429; it surfaces as per-item rejections inside the 202 response. |
Rate limits and retries
API rate limit exceeded. Slow down and retry after the current window resets. Plan event quota exhaustion on this endpoint never returns a batch-level 429; it surfaces as per-item rejections inside the 202 response.
Retries are safe: events are deduplicated by their idempotency_key, so resending an event that already landed will not double-count it.