Lucius API
Usage

List usage events

Returns a paginated list of usage events, newest first. Filter by contract, metric, date range, or rating status.

GET
/v1/billing/usage

Authorization

AuthorizationBearer <token>

API key as Bearer token: Authorization: Bearer luc_live_...

In: header

Query Parameters

contract?string

Filter by contract external ID.

metric?string

Filter by metric name.

from?string

Start of service period (YYYY-MM-DD).

Formatdate
to?string

End of service period (YYYY-MM-DD).

Formatdate
status?string

Filter by event status.

Value in"accepted" | "rated"
limit?integer

Number of items to return (1–100, default: 50).

Default50
Range1 <= value <= 100
starting_after?string

Event ID to paginate after (cursor-based).

Response Body

application/json

application/json

curl -X GET "https://api.lucius.finance/v1/billing/usage?contract=acme-corp-2026&metric=revenue_amount_invoiced"
{
  "object": "list",
  "data": [
    {
      "object": "usage_event",
      "id": "evt-2026-03-001",
      "contract": "acme-corp-2026",
      "metric": "revenue_amount_invoiced",
      "quantity": 10000,
      "service_period_start": "2026-03-25",
      "service_period_end": "2026-03-25",
      "ingested_at": "2026-03-05T11:21:59.868Z",
      "status": "rated"
    }
  ],
  "has_more": false,
  "total_count": 1
}

{
  "error": "Missing API key"
}

Submit usage events

Submit up to 100 usage events in a single request. Each event is validated against the contract's pricing program, persisted, rated immediately, and the corresponding invoice is updated. Events are idempotent — submitting the same `event_id` twice returns success without creating a duplicate.

Get a usage event

Retrieve a single usage event by its idempotency key (`event_id`).