> ## Documentation Index > Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt > Use this file to discover all available pages before exploring further. # Get API usage > Get current usage statistics for your account. Shows detail view and list record consumption, limits, and tier information. ## OpenAPI ````yaml /openapi.yaml get /usage openapi: 3.0.3 info: title: COLA Cloud API description: > Access the United States TTB COLA Registry through COLA Cloud's self-service API. ## Overview COLA Cloud provides programmatic access to the 2005-forward application database for Certificate of Label Approval (COLA) data from the Alcohol and Tobacco Tax and Trade Bureau (TTB). Bulk warehouse delivery remains available separately through a data license. The self-service API includes: - 2005-forward approved alcohol labels - Product details, brand information, and approval dates - Label images with barcodes and QR codes - Permittee (permit holder) information - LLM-enriched data including tasting notes and category classification ## Authentication Self-serve REST, SDK, and CLI requests use a COLA Cloud API key. Include your key in the `X-API-Key` header: ``` curl -H "X-API-Key: your_api_key_here" https://app.colacloud.us/api/v1/colas ``` MCP clients may pass the same API key as `Authorization: Bearer `. Linked assistant OAuth connections may also call the API with a WorkOS-issued Bearer token. OAuth access is scoped per connected app and is in private rollout until account linking is self-serve. ## Quotas Usage is metered by **detail views** (single-record lookups) and **list records** (items returned by list/search endpoints), not raw request count. Quotas are per-user across all channels (web, API, SDKs, CLI, MCP). | Tier | Detail Views/mo | List Records/mo | Burst/min | |------|----------------|-----------------|-----------| | Free | 200 | 10,000 | 10 | | Starter | 2,000 | 100,000 | 60 | | Pro | 10,000 | 1,000,000 | 120 | Quota headers are included in all responses: - `X-Detail-Views-Limit`: Your monthly detail view limit - `X-Detail-Views-Remaining`: Detail views remaining this month - `X-List-Records-Limit`: Your monthly list record limit - `X-List-Records-Remaining`: List records remaining this month - `X-Quota-Reset`: Unix timestamp when quotas reset ## Pagination List endpoints support pagination via `page` and `per_page` parameters: - `page`: Page number (default: 1) - `per_page`: Results per page (default: 20, max: 100) Responses include pagination metadata: ```json { "data": [...], "pagination": { "mode": "offset", "page": 1, "per_page": 20, "total": null, "pages": null, "has_more": true } } ``` For deep result sets, use **cursor-based pagination** with the `cursor` parameter (returned as `next_cursor` in the response). Cursor pagination performs consistently regardless of depth. version: 1.0.0 contact: name: COLA Cloud Support email: help@colacloud.us url: https://colacloud.us license: name: Proprietary url: https://colacloud.us/terms servers: - url: https://app.colacloud.us/api/v1 description: Production server security: - ApiKeyHeader: [] - BearerApiKey: [] tags: - name: COLAs description: Certificate of Label Approval operations - name: Permittees description: Permit holder operations - name: Barcodes description: Barcode lookup operations - name: Usage description: API usage and rate limit information - name: Saved Searches description: Durable saved-search and scheduled alert operations - name: Reference Data description: > Free reference datasets from the TTB. These endpoints require an API key but do not count against your monthly quota. paths: /usage: get: tags: - Usage summary: Get API usage description: > Get current usage statistics for your account. Shows detail view and list record consumption, limits, and tier information. operationId: getUsage responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/UsageStats' example: data: tier: free current_period: 2024-01 detail_views: used: 42 limit: 200 remaining: 158 list_records: used: 150 limit: 500 remaining: 350 per_minute_limit: 10 '401': $ref: '#/components/responses/Unauthorized' components: schemas: UsageStats: type: object properties: tier: type: string enum: - free - starter - pro description: Your account tier current_period: type: string description: Current billing period (YYYY-MM) detail_views: $ref: '#/components/schemas/UsageQuota' list_records: $ref: '#/components/schemas/UsageQuota' per_minute_limit: type: integer description: Maximum requests per minute (burst limit) UsageQuota: type: object description: Usage quota for a single meter properties: used: type: integer description: Amount used this period limit: type: integer description: Maximum allowed this period remaining: type: integer description: Amount remaining this period Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: object additionalProperties: true description: Additional error metadata required: - code - message - details required: - error responses: Unauthorized: description: Missing or invalid API key or Bearer token content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_key: summary: Missing API key or Bearer token value: error: code: unauthorized message: >- API key required. Provide via X-API-Key header or Authorization: Bearer. details: {} invalid_key: summary: Invalid API key value: error: code: unauthorized message: Invalid API key. details: {} revoked_key: summary: Revoked API key value: error: code: unauthorized message: This API key has been revoked. details: {} oauth_connection_required: summary: OAuth connection is not linked value: error: code: oauth_connection_required message: No COLA Cloud account is linked to this OAuth connection. details: {} securitySchemes: ApiKeyHeader: type: apiKey in: header name: X-API-Key description: API key passed in the X-API-Key header BearerApiKey: type: http scheme: bearer description: | API key passed as `Authorization: Bearer `, or a linked WorkOS OAuth access token passed as `Authorization: Bearer `. API keys are equivalent to the X-API-Key scheme. OAuth tokens must include the scope required by the endpoint. ````