# Usage — API reference

Credits, storage and egress for the current period.

## GET /v1/limits

Machine-readable capabilities: supported formats with their byte ceilings, the operation catalogue with class and per-megabyte pricing, processing limits, and per-organization velocity ceilings. Read from the same constants the enforcing code reads.

Responses

| Status | Description |
| --- | --- |
| `200` | The current limits. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## POST /v1/estimate

The same arithmetic job acceptance runs: the answer is the number a created job would reserve. Naturally idempotent — the same question always gets the same answer.

Parameters

| Name | In | Requirement | Description |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | Required | Client-generated key, scoped to (organization, endpoint) and retained 24 hours. A replay with the same body returns the stored response without re-executing or re-billing; a replay with a different body returns 409. |

Request body

| Field | Type | Requirement | Description |
| --- | --- | --- | --- |
| `operation` | `string` | Required |  |
| `byte_size` | `integer` | Required |  |

Responses

| Status | Description |
| --- | --- |
| `200` | The estimate. |
| `400` | Codes: invalid_request, unsupported_file, file_too_large, corrupted_file, encrypted_file, unsupported_operation. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |

## GET /v1/usage

Consumption for the current billing period. This is the authoritative record — never derive usage from gateway throttling counters.

Responses

| Status | Description |
| --- | --- |
| `200` | Usage for the current period. |
| `401` | Codes: missing_credentials, invalid_api_key, expired_api_key, revoked_api_key, api_key_in_query. |
| `403` | Codes: insufficient_scope, ip_not_allowed, environment_mismatch, organization_suspended, forbidden, key_restricted. |
| `429` | Rate limited or out of credits. Retry after the interval in `Retry-After`. Codes: key_spend_limit, rate_limited, concurrency_limit, credits_exhausted. |
| `500` | Codes: internal_error. |
| `503` | Codes: processing_unavailable, dependency_unavailable. |
| `504` | Codes: timeout. |