> ## Documentation Index > Fetch the complete documentation index at: https://agents-docs.hockeystack.com/llms.txt > Use this file to discover all available pages before exploring further. # Aggregated credit usage over a time window > Returns aggregated usage in the requested window. Default window is the last 30 days. `group_by` controls aggregation: - `feature` — one row per feature - `day` — one row per UTC day - `feature,day` — one row per feature+day combination ## OpenAPI ````yaml https://app.hockeystack.com/api/revenue-agents/v1/openapi.json get /credits/usage openapi: 3.1.0 info: title: HockeyStack Revenue Agents API version: v1 description: | Headless HTTP API for HockeyStack Revenue Agents. Auth: Bearer ApiToken (`hsr_live_`) in the Authorization header. contact: name: HockeyStack Support email: support@hockeystack.com servers: - url: https://app.hockeystack.com/api/revenue-agents/v1 description: Production security: - bearerAuth: [] tags: - name: Service description: Health checks and token introspection. - name: Agents description: Deal- and company-agent lifecycle. - name: Conversations description: > Send messages to a deal or company agent. Two transports: - **REST blocking (default):** request returns when the agent finishes. Response shape: `{ conversation_id, messages: [...] }`. - **SSE streaming:** opt in via `Accept: text/event-stream` header or `{ stream: true }` body field. Events emitted: - `text_delta { content }` — incremental assistant tokens - `tool_use { id, tool_name }` — agent is calling a tool - `tool_result { id }` — tool finished (return value not exposed in v1) - `done { conversation_id, messages }` — final state, same shape as REST response - `error { code, category, message }` — failure - name: Tasks description: | Agent-generated and manually-created tasks. Public status enum: `pending | completed | dismissed | cancelled`. Additional internal states are not exposed. - name: Credits description: | Workspace credit usage and limit state. There is no pre-paid balance pool to draw down — the model is a per-month usage counter against an included bundle plus an optional on-demand cap. Use these endpoints to detect approaching spend caps before hitting a 503. paths: /credits/usage: get: tags: - Credits summary: Aggregated credit usage over a time window description: | Returns aggregated usage in the requested window. Default window is the last 30 days. `group_by` controls aggregation: - `feature` — one row per feature - `day` — one row per UTC day - `feature,day` — one row per feature+day combination operationId: getCreditsUsage parameters: - name: from in: query description: | Inclusive lower bound. Accepts any string parseable as a date or datetime — `YYYY-MM-DD`, RFC 3339 with or without an offset. Output is always echoed as full ISO 8601 with `Z`. schema: type: string format: date-time - name: to in: query description: | Exclusive upper bound. Accepts any string parseable as a date or datetime. Must be `>= from` (server returns 400 otherwise). schema: type: string format: date-time - name: group_by in: query schema: type: string enum: - feature - day - feature,day default: feature responses: '200': description: Usage page. content: application/json: schema: $ref: '#/components/schemas/CreditsUsage' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: schemas: CreditsUsage: type: object required: - from - to - group_by - total_credits_used - groups properties: from: type: string format: date-time to: type: string format: date-time group_by: type: string enum: - feature - day - feature,day total_credits_used: type: number groups: type: array items: type: object required: - credits_used - operation_count properties: feature: type: - string - 'null' day: type: - string - 'null' credits_used: type: number operation_count: type: integer Error: type: object required: - error properties: error: type: object required: - code - category - message - request_id properties: code: type: string description: Stable error code. Never renamed or removed within /v1. category: type: string enum: - permanent - transient - rate_limited description: | `permanent` — fix the request. `transient` — retry with backoff. `rate_limited` — retry after the Retry-After header. message: type: string description: Human-readable English message. Wording may change. request_id: type: string description: Trace ID for support tickets. Same as X-Request-Id header. details: type: object description: Code-specific structured data. responses: BadRequest: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid token. content: application/json: schema: $ref: '#/components/schemas/Error' examples: tokenMissing: value: error: code: auth.token_missing category: permanent message: 'Missing Authorization: Bearer header.' request_id: req_abc tokenInvalid: value: error: code: auth.token_invalid category: permanent message: API token is invalid, expired, or revoked. request_id: req_abc RateLimited: description: Per-token or per-IP rate limit exceeded. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-RateLimit-Pool: $ref: '#/components/headers/RateLimitPool' X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' content: application/json: schema: $ref: '#/components/schemas/Error' Unavailable: description: An upstream dependency is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' headers: RetryAfter: description: Seconds until retry is allowed. schema: type: integer RateLimitPool: description: Pool that consumed a point for this request (`read` or `write`). schema: type: string enum: - read - write RateLimitLimit: description: Maximum requests allowed in the current window for this pool. schema: type: integer RateLimitRemaining: description: Requests remaining in the current window. schema: type: integer RateLimitReset: description: Unix timestamp when the bucket refills. schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: hsr_live ````