Usage

Overview

The Usage API lets you track how many operations your organization has consumed in the current billing period, check your plan limit, and browse individual usage events. An operation is any billable event: case runs, notarized actions, chat messages, compliance bundles, settlements, or drift checks. See Billing for the full list.

Get Usage Summary

GET /api/v1/usage
Authorization: Bearer aira_live_xxxxx

Returns your current period usage, plan limit, and the per-event-type breakdown.

Example Response

{
  "usage": 1247,
  "limit": 10000,
  "remaining": 8753,
  "plan": "pro",
  "overage_ops": 0,
  "overage_cost": "0",
  "overage_enabled": true,
  "breakdown": {
    "case_runs": 42,
    "action_authorizations": 1150,
    "chat_messages": 40,
    "compliance_bundles": 5,
    "settlements": 2,
    "drift_checks": 8
  },
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`usage`	integer	Total operations consumed in the current billing period
`limit`	integer	Maximum operations allowed by your plan
`remaining`	integer	Operations remaining (`limit - usage`)
`plan`	string	Your current plan name (`free`, `pro`, `business`, `enterprise`, `selfhosted`)
`overage_ops`	integer	Operations counted above `limit` (0 if within plan)
`overage_cost`	string	Estimated overage cost in euros (decimal string)
`overage_enabled`	boolean	Whether overage is billable on this plan
`breakdown`	object	Counts per billable event type

When limit is -1, the plan has unlimited operations (enterprise and self-hosted). In this case, remaining is also -1.

Usage resets at the start of each billing period. When remaining reaches 0 on a plan with overage_enabled: false (Free), the next billable request returns 429 PLAN_LIMIT_EXCEEDED.

List Usage Events

GET /api/v1/usage/events?page=1&per_page=20
Authorization: Bearer aira_live_xxxxx

Returns a paginated list of individual usage events — one entry per billable action.

Example Response

{
  "data": [
    {
      "id": "ue_01J8X...",
      "event": "case.execute",
      "units": 1,
      "run_uuid": "prn_01J8X...",
      "metadata": { "models_count": 3 },
      "created_at": "2026-03-14T10:30:59Z"
    },
    {
      "id": "ue_02K9Y...",
      "event": "case.execute",
      "units": 1,
      "run_uuid": "prn_02K9Y...",
      "metadata": null,
      "created_at": "2026-03-14T09:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1247,
    "has_more": true
  },
  "request_id": "req_..."
}

Event Fields

Field	Type	Description
`event`	string	The billable action type (e.g. `case.execute`)
`units`	integer	Number of units consumed (typically 1 per case)
`run_uuid`	string\|null	Associated case run ID
`metadata`	object\|null	Additional event metadata
`created_at`	string	When the event occurred (ISO 8601 UTC)

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number (min: 1)
`per_page`	integer	20	Results per page (1-100)

On this page