> ## Documentation Index > Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregated usage metrics > Time-bucketed aggregates of every generation your team has dispatched. Buckets are returned newest-first. Pass `bucket_width` to control the bucket size; pass `group_by[]` to slice each bucket by status, key, user, or modality. Idempotent: GET is naturally safe to retry; no `Idempotency-Key` is required. Pagination is opaque-cursor (`page_token`); the cursor expires 24h after issue and is invalidated when query parameters change between pages. Headers `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `Retry-After` (on 429) are returned on every response. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/usage openapi: 3.0.0 info: title: Aurous Labs API description: >- Generate AI images with custom LoRA styles. ## Authentication All requests require an API key passed in the `X-Api-Key` header. Create API keys in your [dashboard](https://app.aurous-labs.com/dashboard/api-keys). ## Closed-beta access gate API keys are scoped to a user. If that user's account is not approved for the closed beta, every request returns `403` with one of these `error.code` values: - `account_pending` — awaiting review - `account_rejected` — declined post-signup - `account_suspended` — was approved, then suspended There is no retry — contact support to be approved. The same codes are emitted by the WebSocket gateway via 4001 close. ## Common headers Every response carries `Aurous-Request-Id` (a server-minted `req_` for support tracing) and `Aurous-Version` (the API version applied to the response). Optionally pin a version on the request with `Aurous-Version: YYYY-MM-DD` — defaults to your team's pinned version. ## Quick Start ```bash curl -X POST https://api.aurous-labs.com/v1/images \ -H "X-Api-Key: al_live_your_key" \ -H "Content-Type: application/json" \ -d '{"prompt": "A golden sunset over mountains", "lora_id": "your-lora-id", "size": "2k_1_1"}' ``` version: 1.0.0 contact: {} servers: - url: https://api.aurous-labs.com description: Production - url: https://api.preprod.aurous-labs.com description: Preprod (staging) security: [] tags: - name: Seedance (raw) description: >- Drop-in raw passthrough for Seedance video generation. Point the official Seedance provider SDK at this API's base URL and authenticate with your Aurous API key in the `X-Api-Key` header — request bodies are forwarded to the provider verbatim and responses come back shape-identical, so you keep the provider's exact request/response shapes. Task ids are Aurous-native `vid_…` ids. Billing rides response headers, not the body: `Aurous-Credits-Held` on the create response and `Aurous-Credits-Charged` on a settled, succeeded task read — the body itself stays provider-shaped. paths: /v1/usage: get: tags: - Public API (v1) summary: Aggregated usage metrics description: >- Time-bucketed aggregates of every generation your team has dispatched. Buckets are returned newest-first. Pass `bucket_width` to control the bucket size; pass `group_by[]` to slice each bucket by status, key, user, or modality. Idempotent: GET is naturally safe to retry; no `Idempotency-Key` is required. Pagination is opaque-cursor (`page_token`); the cursor expires 24h after issue and is invalidated when query parameters change between pages. Headers `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `Retry-After` (on 429) are returned on every response. operationId: V1UsageController_getUsage parameters: - name: start_time required: true in: query description: Inclusive lower bound (RFC 3339). schema: example: '2026-04-08T00:00:00Z' type: string - name: end_time required: false in: query description: Exclusive upper bound. Defaults to now. schema: example: '2026-05-08T00:00:00Z' type: string - name: bucket_width required: false in: query description: Bucket size. Default 1d. Each width has a max range cap. schema: enum: - 1m - 5m - 15m - 1h - 1d - 7d type: string - name: group_by required: false in: query description: Optional grouping dims (max 2). schema: type: array items: type: string enum: - status - api_key_id - user_id - type - model - name: status required: false in: query description: >- Filter by status. Comma-separated or repeated. Allowed: `pending`, `processing`, `succeeded`, `failed`, `cancelled` (legacy alias `completed` = `succeeded`). schema: type: array items: type: string - name: type required: false in: query description: Filter by inference type. Comma-separated or repeated. schema: type: array items: type: string - name: api_key_id required: false in: query description: Filter by opaque API-key id (key_). schema: type: array items: type: string - name: user_id required: false in: query description: Filter by opaque user id (usr_). schema: type: array items: type: string - name: lora_id required: false in: query description: Filter by opaque LoRA id (lora_). schema: type: array items: type: string - name: character_id required: false in: query description: Single character filter (char_). schema: example: char_01HVABCDEFGHJKMNPQRSTVWXYZ type: string - name: model required: false in: query description: >- Filter by public model slug (e.g. `aurous-grow-2.0-pro`). Comma-separated or repeated. Unknown slugs return 400 invalid_filter. schema: example: aurous-grow-2.0-pro,aurous-embed-vision-1.0 type: array items: type: string - name: limit required: false in: query description: Items per page (1-100, default 24). schema: minimum: 1 maximum: 100 example: 24 type: number - name: page_token required: false in: query description: Opaque cursor returned in `next_page` from a prior call. 24h TTL. schema: example: eyJ2IjoxLCJxZiI6Ii4uLiJ9 type: string - name: Aurous-Version in: header required: false description: >- Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default `2026-07-16` for unauthenticated requests. schema: type: string example: '2026-07-16' pattern: ^\d{4}-\d{2}-\d{2}$ responses: '200': description: Usage aggregates (newest first). content: application/json: schema: $ref: '#/components/schemas/UsageListResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '400': description: >- invalid_time_range / invalid_bucket_width / too_many_buckets / too_many_group_by / invalid_filter / invalid_page_token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '403': description: API key lacks `read` scope, or account_pending/rejected/suspended. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '429': description: rate_limited — Retry-After header set. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 Retry-After: description: >- Seconds to wait before retrying. Present on 429 (rate limit) and on 503 provider_unavailable. Prefer this over computing X-RateLimit-Reset − now. schema: type: integer example: 12 '500': description: internal_error — includes Aurous request id. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '503': description: >- Temporarily unable to verify account/billing state or prepare the request (error.code: `provider_unavailable`). Retry after the number of seconds in the `Retry-After` header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 Retry-After: description: >- Seconds to wait before retrying. Present on 429 (rate limit) and on 503 provider_unavailable. Prefer this over computing X-RateLimit-Reset − now. schema: type: integer example: 12 security: - api-key: [] components: schemas: UsageListResponse: type: object properties: object: type: string description: Discriminator example: list enum: - list data: description: Buckets in `bucket_start DESC` order. type: array items: $ref: '#/components/schemas/UsageBucketResponse' has_more: type: boolean description: True when more buckets exist beyond this page. example: false next_page: type: object description: >- Pass as `?page_token=` on the next request. Opaque base64; tied to the original query fingerprint. Null when `has_more=false`. 24h expiry. example: null nullable: true required: - object - data - has_more - next_page ErrorResponse: type: object properties: error: description: Error payload allOf: - $ref: '#/components/schemas/ErrorPayload' required: - error UsageBucketResponse: type: object properties: object: type: string description: Discriminator example: usage.bucket enum: - usage.bucket bucket_start: type: string description: Inclusive bucket lower bound (RFC 3339 UTC). example: '2026-05-07T00:00:00Z' bucket_end: type: string description: >- Exclusive bucket upper bound (RFC 3339 UTC). `bucket_end - bucket_start` equals the requested `bucket_width`. example: '2026-05-08T00:00:00Z' groups: description: >- One entry per group key. Always non-empty (a bucket with zero rows is omitted from the response). type: array items: $ref: '#/components/schemas/UsageGroupResponse' required: - object - bucket_start - bucket_end - groups ErrorPayload: type: object properties: type: type: string description: Broad error category example: invalid_request enum: - invalid_request - authentication - not_found - rate_limit - server_error code: type: string description: >- Stable error code (programmatic discriminator). Closed-beta gate emits one of `account_pending`, `account_rejected`, `account_suspended` on 403. example: balance_too_low enum: - invalid_request - missing_field - invalid_format - value_out_of_range - unsupported_lora_for_mode - generation_not_cancellable - prompt_blocked - reference_blocked - output_moderation_rejected - unknown_version - mutually_exclusive_input - character_not_ready - parameter_invalid_combination - style_retired - parameter_invalid - too_many_reference_images - action_not_available - upload_invalid - balance_too_low - idempotency_key_in_use - api_key_not_found - payload_too_large - missing_api_key - invalid_api_key - revoked_api_key - resource_not_found - forbidden_resource - account_pending - account_rejected - account_suspended - already_approved - already_rejected - already_suspended - invalid_reinstate_target - invalid_suspend_target - cannot_moderate_admin - too_many_requests - concurrency_limit_exceeded - tpm_rate_limit_exceeded - internal_error - provider_unavailable - provider_timeout - provider_not_configured - invalid_time_range - invalid_bucket_width - too_many_buckets - too_many_group_by - invalid_filter - invalid_page_token - export_too_large - user_already_exists - self_invite_forbidden - invite_link_failed - invite_rate_limited - model_not_found - model_disabled - model_wrong_kind - max_tokens_exceeds_hard_cap - chat_model_misconfigured - embeddings_input_too_large - embeddings_unsupported_dimensions - pricing_frozen - provider_rate_limited - chat_provider_request_invalid - chat_provider_auth_failed - chat_provider_unavailable - max_input_tokens_exceeded - chat_provider_unknown_error - embeddings_provider_unknown_error - embeddings_batch_not_supported - embeddings_input_too_many_items - embeddings_video_unsupported - encoding_format_unsupported - missing_max_tokens_no_model_default - chat_cancel_target_not_found - chat_completion_not_found - chat_cancel_target_already_terminal - chat_cancel_target_not_cancellable - tool_choice_required_unsupported - response_format_too_large - response_format_too_deep - invalid_cursor - invalid_cursor_for_endpoint - model_slug_exists - output_expired - output_not_available - content_filtered - image_generation_failed - reference_media_invalid - reference_media_cap_reached - reference_fetch_failed - unsupported_auth_method - insufficient_scope - uploads_expired - provider_unknown_error - first_frame_too_small message: type: string description: Human-readable message example: Team available balance is 1.5 credits, generation requires 2.0. param: type: object description: Field name when the error is parameter-scoped example: prompt nullable: true doc_url: type: string description: Documentation link for this error code example: https://docs.aurous-labs.com/errors#balance_too_low request_id: type: string description: Echoes Aurous-Request-Id — quote in support tickets example: req_01HXMQ7Z3K8Y2VNABCDEFGHJKM required: - type - code - message - doc_url - request_id UsageGroupResponse: type: object properties: key: type: object description: >- Group key — values for the dimensions in `group_by`. Empty object `{}` when no `group_by` was sent (single-group bucket totals). When `group_by` includes `model`, the key carries the public model slug (`aurous-grow-2.0-pro`, `aurous-embed-vision-1.0`) and is `null` for image/video buckets that have no LLM activity. example: status: succeeded model: aurous-grow-2.0-pro api_key_id: key_01HVABCDEFGHJKMNPQRSTVWXYZ metrics: description: Aggregated metrics for this group. allOf: - $ref: '#/components/schemas/UsageMetricsResponse' required: - key - metrics UsageMetricsResponse: type: object properties: request_count: type: number description: Total request count in the bucket. example: 142 successful_count: type: number description: Count of generations that reached terminal status `succeeded`. example: 142 failed_count: type: number description: Count of generations that reached terminal status `failed`. example: 0 cancelled_count: type: number description: >- Count of generations cancelled by the caller before terminal completion. example: 0 credits_used: type: number description: >- Sum of credits charged for generations in this bucket. Excludes pending holds; only committed charges count. Rounded to 4 decimals. example: 14.12 duration_ms_p50: type: object description: >- Median end-to-end processing duration (ms) across rows that carry a duration. Null when the bucket has no rows with a populated `duration_ms`. example: 1820 nullable: true duration_ms_p95: type: object description: >- 95th-percentile processing duration (ms). Null when sample size is zero. example: 4310 nullable: true image_count: type: number description: >- Total images produced in the bucket (sum of `image_count` across image generations). example: 142 video_seconds: type: number description: >- Total seconds of video produced in the bucket. Rounded to 2 decimals. example: 0 total_input_tokens: type: number description: >- Total input tokens consumed by chat + embedding inferences in the bucket. Always present and numeric — 0 for buckets with only image/video rows. For chat rows this is `prompt_tokens` (matches OpenAI semantics); for embeddings it is the sum of text + visual + video tokens. example: 1234 total_output_tokens: type: number description: >- Total output tokens emitted by chat inferences in the bucket. Always present and numeric — 0 for buckets without chat rows (image, video, embedding). Embeddings have no output tokens. example: 5678 required: - request_count - successful_count - failed_count - cancelled_count - credits_used - duration_ms_p50 - duration_ms_p95 - image_count - video_seconds - total_input_tokens - total_output_tokens securitySchemes: api-key: type: apiKey in: header name: X-Api-Key description: Your team API key (starts with `al_live_`). ````