Usage

Overview

The Usage API lets you track how many cases your organization has consumed in the current billing period, check your plan limits, and browse individual usage events.

Get Usage Summary

GET /api/v1/usage
Authorization: Bearer aira_live_xxxxx

Returns your current period usage, plan limit, and remaining quota.

Example Response

{
  "usage": 1247,
  "limit": 5000,
  "remaining": 3753,
  "plan": "pro",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`usage`	integer	Cases consumed in the current billing period
`limit`	integer	Maximum cases allowed by your plan
`remaining`	integer	Cases remaining (`limit - usage`)
`plan`	string	Your current plan name (e.g. `starter`, `pro`, `enterprise`, `selfhosted`)

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

Usage resets at the start of each billing period. When remaining reaches 0, case execution returns 429 QUOTA_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_id": "prn_01J8X...",
      "metadata": { "models_count": 3 },
      "created_at": "2026-03-14T10:30:59Z"
    },
    {
      "id": "ue_02K9Y...",
      "event": "case.execute",
      "units": 1,
      "run_id": "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_id`	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