Operations
Usage & billing
Read-only endpoints for entitlement checks, billing-period usage totals, and the API billing ledger.
Summary
Usage summary
This endpoint combines entitlement state, billing-period usage, job totals, and the active rate-limit policy for the calling organization.
| Field | Meaning |
|---|---|
| access.enabled | Whether the org is entitled to API access. |
| billing_period.start_at / end_at | The active billing window for the summary. |
| usage.included / consumed / overage / remaining | Plan capacity and how much remains. |
| jobs.total / succeeded / failed | API job totals for the current billing period. |
| jobs.outputs_returned | How many outputs were returned to the caller. |
| jobs.regenerate_count / cache_hit_count | Regenerations and approved-cache reuse. |
curl https://app.katalo.ai/api/v1/usage/summary \
-H "Authorization: Bearer $KATALO_API_KEY"Ledger
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.
| Field | Meaning |
|---|---|
| event_id | Public usage event id. |
| job_id | Public generation job id. |
| source_asset_id | Public source asset id. |
| usage_type | The billable usage bucket. |
| config_fingerprint | Stable hash for reconciliation. |
| billable | Whether this event was billable. |
| unit_price_usd / amount_usd | Dollar values for accounting. |
Reconciliation
Reconciliation guidance
Use public identifiers from the ledger to reconcile internal records without depending on hidden internal ids.
Recommended keys
Use event_id, job_id, and config_fingerprint as your primary reconciliation keys.