# Usage (/docs/api/usage)

The calling key's own usage: its requests and the credits they used.

## Get Usage

`GET https://api.presentations.ai/api/v1/usage`

Return requests, success rate, durations and credits for this key.

**Query parameters**

- `since` (string (date-time), optional) — Only requests created at or after this time (ISO 8601 with timezone).
- `until` (string (date-time), optional) — Only requests created before this time (ISO 8601 with timezone).

**Responses**

- `200`: APIUsageSummary — Successful Response
- `401`: APIErrorResponse — Missing, malformed, expired, or revoked Bearer API key. `error.code`: `UNAUTHENTICATED`, `INVALID_TOKEN`.
- `403`: APIErrorResponse — The API key, workspace role, project scope, or plan lacks permission. `error.code`: `FORBIDDEN`, `FEATURE_NOT_IN_PLAN`, `PLAN_LIMIT_EXCEEDED`.
- `422`: RequestValidationErrorResponse — A path, query, header, or request-body field failed validation. `error.code`: `VALIDATION_FAILED`.
- `429`: APIErrorResponse — The caller exceeded the API rate limit. `error.code`: `RATE_LIMITED`.
- `500`: APIErrorResponse — Unexpected server failure. Retry only idempotent operations and retain trace_id. `error.code`: `INTERNAL_ERROR`.

## List Usage Requests

`GET https://api.presentations.ai/api/v1/usage/requests`

List the deck-generation requests this key made, newest first.

**Query parameters**

- `since` (string (date-time), optional) — Only requests created at or after this time (ISO 8601 with timezone).
- `until` (string (date-time), optional) — Only requests created before this time (ISO 8601 with timezone).
- `status` (AsyncTaskStatus, optional) — Only requests in this state.
- `page` (integer, optional, ≥ 1, default `1`) — Page number, starting at 1.
- `limit` (integer, optional, ≥ 1, ≤ 200, default `50`) — Items per page.

**Responses**

- `200`: Page_APIUsageRequest_ — Successful Response
- `401`: APIErrorResponse — Missing, malformed, expired, or revoked Bearer API key. `error.code`: `UNAUTHENTICATED`, `INVALID_TOKEN`.
- `403`: APIErrorResponse — The API key, workspace role, project scope, or plan lacks permission. `error.code`: `FORBIDDEN`, `FEATURE_NOT_IN_PLAN`, `PLAN_LIMIT_EXCEEDED`.
- `422`: RequestValidationErrorResponse — A path, query, header, or request-body field failed validation. `error.code`: `VALIDATION_FAILED`.
- `429`: APIErrorResponse — The caller exceeded the API rate limit. `error.code`: `RATE_LIMITED`.
- `500`: APIErrorResponse — Unexpected server failure. Retry only idempotent operations and retain trace_id. `error.code`: `INTERNAL_ERROR`.

# Schemas

### APIUsageFeature

Credits one feature consumed.

- `feature` (string, required) — Display name of the billed feature.
- `credits` (integer, required) — Credits the feature consumed.
- `uses` (integer, required) — Number of charges for the feature.

### APIUsageKey

One key's share of the usage.

- `api_key_id` (string (uuid), required) — API key id.
- `name` (string, required) — Key name; null if the key no longer exists.
- `prefix` (string, required) — Display-safe key prefix; null if the key no longer exists.
- `requests` (integer, required) — Generation requests made with the key.
- `credits_consumed` (integer, required) — Credits charged to the key.

### APIUsageRequest

One deck-generation request made with an API key.

- `task_id` (string (uuid), required) — Generation task id.
- `request_id` (string, required) — The caller's `Request-Id`; null for runs started without one.
- `api_key_id` (string (uuid), required) — Key that started the run.
- `deck_id` (string (uuid), required) — Deck generated.
- `status` (AsyncTaskStatus, required) — Lifecycle state.
- `stage` (GenerationStage, required) — Last recorded generation stage.
- `created_at` (string (date-time), required) — When the request was accepted.
- `finished_at` (string (date-time), required) — When it completed or failed; null while in progress.
- `duration_seconds` (number, required) — Seconds from acceptance to finish; null while in progress.
- `credits_consumed` (integer, required) — Credits charged to the deck by this key.
- `error` (string, required) — Failure message; null unless `FAILED`.

### APIUsageRequestCounts

Deck-generation requests by lifecycle outcome.

- `total` (integer, required) — All generation requests in the window.
- `completed` (integer, required) — Requests that finished `COMPLETED`.
- `failed` (integer, required) — Requests that finished `FAILED`.
- `in_progress` (integer, required) — Requests not yet finished.

### APIUsageSummary

Usage over a window, for one key or for every key in scope.

- `workspace_id` (string (uuid), required) — Workspace the usage belongs to.
- `api_key_id` (string (uuid), required) — Key the summary is limited to; null when it covers every key in scope.
- `since` (string (date-time), required) — Inclusive window start; null for unbounded.
- `until` (string (date-time), required) — Exclusive window end; null for unbounded.
- `requests` (APIUsageRequestCounts, required) — Generation requests by outcome.
- `success_rate` (number, required) — Percent (0-100) of finished requests that completed; null until one finishes.
- `avg_duration_seconds` (number, required) — Mean seconds from acceptance to finish over finished requests.
- `credits_consumed` (integer, required) — Total credits charged in the window.
- `by_feature` (APIUsageFeature[], required) — Credits by feature, highest first.
- `by_key` (APIUsageKey[], required) — Usage per key, most credits first.

### AsyncTaskStatus

Lifecycle state of an async task: CREATED (queued), RUNNING, then COMPLETED or FAILED.

One of: `CREATED`, `RUNNING`, `COMPLETED`, `FAILED`

### GenerationStage

Deck generation moves QUEUED, OUTLINE, SLIDES, EXPORT, then COMPLETED or FAILED.

One of: `QUEUED`, `OUTLINE`, `SLIDES`, `EXPORT`, `COMPLETED`, `FAILED`

### Page_APIUsageRequest_

- `data` (APIUsageRequest[], required) — Items on this page.
- `page` (integer, required) — 1-based page number returned.
- `limit` (integer, required) — Maximum items per page.
- `total` (integer, required) — Items matching the filters across all pages.