> ## Documentation Index
> Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage & billing

> Read-only endpoints for entitlement checks, billing-period usage totals, and the API billing ledger.

## Usage summary

The usage summary endpoint combines entitlement state, billing-period usage, job totals, and the active rate-limit policy for the calling organization.

```http theme={null}
GET /api/v1/usage/summary
```

```bash theme={null}
curl https://app.katalo.ai/api/v1/usage/summary \
  -H "Authorization: Bearer $KATALO_API_KEY"
```

| Field            | Meaning                                           |
| ---------------- | ------------------------------------------------- |
| `entitlement`    | Current API access and billing entitlement state. |
| `billing_period` | Active billing period boundaries.                 |
| `usage`          | Billing-period usage totals.                      |
| `jobs`           | Job totals by state.                              |
| `rate_limits`    | Active limit policy for the calling organization. |

## Billing events ledger

The billing events endpoint is a cursor-paginated ledger of API-originated usage events. Use it for reconciliation and audit, not job state.

```http theme={null}
GET /api/v1/billing/events
```

```bash theme={null}
curl "https://app.katalo.ai/api/v1/billing/events?limit=100" \
  -H "Authorization: Bearer $KATALO_API_KEY"
```

| Field                | Meaning                                                       |
| -------------------- | ------------------------------------------------------------- |
| `event_id`           | Stable public id for the ledger event.                        |
| `job_id`             | Generation job associated with the billing event.             |
| `usage_type`         | Usage category recorded by the API.                           |
| `config_fingerprint` | Stable fingerprint for distinct configuration reconciliation. |
| `created_at`         | Time the billing event was recorded.                          |
| `next_cursor`        | Cursor for the next page, if more results are available.      |

## Reconciliation guidance

Use `event_id`, `job_id`, and `config_fingerprint` as your primary reconciliation keys. They are public identifiers and do not require depending on hidden internal ids.