> ## Documentation Index > Fetch the complete documentation index at: https://docs.trycaesar.com/llms.txt > Use this file to discover all available pages before exploring further. # Get organization usage > Usage analytics for the API key's organization: request and error totals, latency, per-key and per-endpoint breakdowns, and billable product spend. Defaults to the last 30 days in day buckets (UTC). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/usage openapi: 3.1.0 info: description: >- Local implementation of the v1 search, document, feedback, and internal operational APIs. title: Agent Search API (Public) version: 0.1.0 servers: - description: Staging url: https://alpha.api.trycaesar.com - description: Local development url: http://localhost:8080 security: [] tags: - description: Public search APIs. name: Search - description: Public document inspection APIs. name: Documents - description: Public feedback ingestion APIs. name: Feedback - description: Asynchronous deep-research APIs. name: Research - description: Internal health, readiness, and metrics APIs. name: Operations paths: /v1/usage: get: tags: - Usage summary: Get organization usage description: >- Usage analytics for the API key's organization: request and error totals, latency, per-key and per-endpoint breakdowns, and billable product spend. Defaults to the last 30 days in day buckets (UTC). operationId: get-usage parameters: - description: 'Window start (ISO 8601). Default: 30 days before to.' explode: false in: query name: from schema: description: 'Window start (ISO 8601). Default: 30 days before to.' type: string - description: 'Window end (ISO 8601). Default: now.' explode: false in: query name: to schema: description: 'Window end (ISO 8601). Default: now.' type: string - description: >- Bucket size for the series. Default day; hour requires a range of at most 8 days. explode: false in: query name: interval schema: description: >- Bucket size for the series. Default day; hour requires a range of at most 8 days. enum: - '' - hour - day type: string - description: Comma-separated API key uuids to filter by (at most 50). explode: false in: query name: api_key_ids schema: description: Comma-separated API key uuids to filter by (at most 50). type: string - description: Optional grouping of the request series. explode: false in: query name: group_by schema: description: Optional grouping of the request series. enum: - '' - none - api_key - endpoint - status_class type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/UsageOverviewResponse' description: Organization usage overview. '400': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Invalid range or filter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Missing or invalid API key. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: API key does not have the required scope. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Rate limited. '502': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Usage service unreachable. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' description: Usage endpoint is not configured. security: - bearerApiKey: [] components: schemas: UsageOverviewResponse: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://alpha.api.trycaesar.com/UsageOverviewResponse.json format: uri readOnly: true type: string endpoints: description: Per-route breakdown, requests desc. items: $ref: '#/components/schemas/UsageEndpointSummary' type: - array - 'null' headline: $ref: '#/components/schemas/UsageHeadline' description: Window totals. keys: description: Per-API-key breakdown, requests desc. items: $ref: '#/components/schemas/UsageKeySummary' type: - array - 'null' latency_series: description: Latency per bucket, ungrouped. items: $ref: '#/components/schemas/UsageLatencyPoint' type: - array - 'null' products: description: Billable products and spend. items: $ref: '#/components/schemas/UsageProductSummary' type: - array - 'null' range: $ref: '#/components/schemas/UsageRange' description: The resolved query window. series: description: Requests per bucket, zero-filled. items: $ref: '#/components/schemas/UsageSeriesPoint' type: - array - 'null' required: - range - headline - series - latency_series - keys - endpoints - products type: object ErrorEnvelope: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://alpha.api.trycaesar.com/ErrorEnvelope.json format: uri readOnly: true type: string error: $ref: '#/components/schemas/ErrorBody' description: Error details. request_id: description: Server request identifier. type: string type: description: Envelope discriminator. enum: - error type: string required: - type - request_id - error type: object UsageEndpointSummary: additionalProperties: false properties: errors: description: 4xx/5xx responses on this route. format: int64 type: integer label: description: Human label for known routes; raw route otherwise. type: string p95_duration_ms: description: 95th-percentile duration on this route. format: double type: number requests: description: Requests to this route. format: int64 type: integer route: description: Public API route, e.g. /v1/search. type: string required: - route - label - requests - errors - p95_duration_ms type: object UsageHeadline: additionalProperties: false properties: avg_duration_ms: description: Mean request duration. format: double type: number error_rate: description: errors / requests; 0 when there are no requests. format: double type: number errors: description: Requests that answered 4xx or 5xx. format: int64 type: integer p95_duration_ms: description: 95th-percentile request duration. format: double type: number requests: description: Total API requests in the window. format: int64 type: integer spend_cents: description: Billable platform spend in exact (possibly fractional) cents. format: double type: number required: - requests - errors - error_rate - avg_duration_ms - p95_duration_ms - spend_cents type: object UsageKeySummary: additionalProperties: false properties: api_key_id: description: API key identifier. type: string errors: description: 4xx/5xx responses attributed to this key. format: int64 type: integer key_prefix: description: Public key prefix (never the secret). type: string last_used_at: description: Most recent request time (RFC 3339). type: string name: description: Key name; deleted keys are suffixed "(deleted)". type: string p95_duration_ms: description: 95th-percentile duration for this key. format: double type: number requests: description: Requests attributed to this key. format: int64 type: integer spend_cents: description: Billable spend attributed to this key, exact cents. format: double type: number status: description: Key lifecycle state. enum: - active - deleted type: string required: - api_key_id - name - key_prefix - status - requests - errors - p95_duration_ms - last_used_at - spend_cents type: object UsageLatencyPoint: additionalProperties: false properties: avg_duration_ms: description: Mean request duration in this bucket. format: double type: number bucket: description: Bucket start (RFC 3339, UTC-aligned). type: string p95_duration_ms: description: 95th-percentile duration in this bucket. format: double type: number required: - bucket - avg_duration_ms - p95_duration_ms type: object UsageProductSummary: additionalProperties: false properties: label: description: Human product label. type: string product: description: Billable product identifier (web_search, document_get, research). type: string requests: description: Metered billable count. format: int64 type: integer spend_cents: description: Spend for this product in the window. format: double type: number required: - product - label - requests - spend_cents type: object UsageRange: additionalProperties: false properties: from: description: Window start (RFC 3339, inclusive). type: string interval: description: Bucket size of the series. enum: - hour - day type: string timezone: description: Always UTC. type: string to: description: Window end (RFC 3339, exclusive). type: string required: - from - to - interval - timezone type: object UsageSeriesPoint: additionalProperties: false properties: bucket: description: Bucket start (RFC 3339, UTC-aligned). type: string errors: description: 4xx/5xx responses in this bucket. format: int64 type: integer group_id: description: Group identifier when the series is grouped, null otherwise. type: - string - 'null' group_label: description: Human label for the group, null when ungrouped. type: - string - 'null' requests: description: Requests in this bucket. format: int64 type: integer required: - bucket - group_id - group_label - requests - errors type: object ErrorBody: additionalProperties: false properties: code: description: Stable machine-readable error code. type: string details: additionalProperties: {} description: Optional structured error details. type: object message: description: Human-readable error message. type: string required: - code - message type: object securitySchemes: bearerApiKey: bearerFormat: API key scheme: bearer type: http ````