Usage API¶

Track API usage and limits for your organization.

Overview¶

The Usage API provides insights into your organization's API consumption, including monthly usage counts, plan limits, and detailed event logs.

Base Path: /api/v1/usage

Authentication: Required for all endpoints (Bearer token)

Endpoints¶

Get Current Monthly Usage¶

Get usage statistics for the current month, including success/error counts and plan limits.

Endpoint: GET /usage/monthly

Response:

{
  "success_count": 150,
  "error_count": 2,
  "last_event_at": "2024-03-15T10:30:00Z",
  "year_month": "2024-03",
  "limit": 1000,
  "plan": "Pro",
  "remaining": 850
}

Get Monthly Usage by Month¶

Get usage statistics for a specific historical month.

Endpoint: GET /usage/monthly/{year_month}

Path Parameters:

Parameter	Type	Required	Description
`year_month`	string	Yes	The month to retrieve (format: `YYYY-MM`)

Response:

Returns the same structure as the current monthly usage endpoint.

Get Usage Stats¶

Get comprehensive usage statistics, including current month stats and limit information.

Endpoint: GET /usage/stats

Response:

Returns a detailed statistics object.

List Claim Events¶

List individual claim processing events with pagination and filtering.

Endpoint: GET /usage/events

Query Parameters:

Parameter	Type	Default	Description
`skip`	integer	0	Number of records to skip
`limit`	integer	100	Maximum records to return
`outcome`	string	null	Filter by outcome (e.g., "success", "error")

Response:

{
  "data": [
    {
      "id": "evt_123",
      "occurred_at": "2024-03-15T10:30:00Z",
      "outcome": "success",
      "details": "Processed claim 12345"
    }
  ],
  "count": 152
}

Check Usage Limit¶

Check if the organization has exceeded its usage limit.

Endpoint: GET /usage/check-limit

Response:

Returns the current usage status without enforcing limits.

{
  "org_id": "org_123",
  "current_usage": 150,
  "limit": 1000,
  "is_over_limit": false,
  "remaining": 850
}