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.

POST https://api.bearlumen.com/v1/usage-events/batch

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 example

Success response (202):

{
  "accepted": 2,
  "failed": 1,
  "results": [
    {
      "event_id": "7372eff3-6ad4-51e1-9be5-539a62e63e79",
      "index": 0,
      "message": "Event accepted for processing",
      "status": "accepted"
    },
    {
      "event_id": "70cd7d44-3f86-535a-8c55-5f80f202e234",
      "index": 1,
      "message": "Event accepted for processing",
      "status": "accepted"
    },
    {
      "error": "event_invoked_at must be a valid ISO 8601 date",
      "index": 2,
      "message": "event_invoked_at must be a valid ISO 8601 date",
      "status": "rejected"
    }
  ]
}

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.