> ## Documentation Index > Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Prompt Usage > Return prompt usage for the organization that owns the given product as flat count buckets, always grouped by product. Use the repeatable breakdown_by parameter to control dimensions (user, origin, date); by default counts are broken down by origin, aggregated over the whole window. The API key authorizes its own product, but the response covers every product in that organization so a single key gives org-wide visibility. Counts cover all prompt origins unless the origin parameter is supplied. Requires prompt usage tracking to be enabled for the organization. Dates are optional and default to the last 30 days. Returns prompt usage for the organization that owns the given product as flat count buckets, always grouped by product. Use the repeatable `breakdown_by` parameter to control dimensions — `user`, `origin` (`APP`, `SLACK` or `API_KEY`) and `date` (UTC calendar day) — in any combination. By default counts are broken down by `origin`, aggregated over the whole window. Your API key authorizes its own product, but the response covers **every product in that organization**, so a single key gives org-wide visibility. Requires prompt usage tracking to be enabled for your organization. Both dates are optional: `end_date` defaults to today (UTC) and `start_date` to 30 days before `end_date`, so calling with no date parameters returns the last 30 days. The response always echoes the resolved window. Dimension fields appear on rows only when the matching `breakdown_by` value was requested. ```text Example request theme={null} GET /api/v1/products/{product_id}/usage/prompts ?start_date=2026-05-01&end_date=2026-05-31 &breakdown_by=user&breakdown_by=origin ``` ```json Example response theme={null} { "start_date": "2026-05-01", "end_date": "2026-05-31", "breakdown_by": ["user", "origin"], "total_prompts": 12, "rows": [ { "product_id": "00000000-0000-0000-0000-000000000000", "product_name": "Acme Analytics", "user_id": "11111111-1111-1111-1111-111111111111", "user_email": "jane@acme.com", "origin": "APP", "prompt_count": 12 } ] } ``` ## OpenAPI ````yaml get /api/v1/products/{product_id}/usage/prompts openapi: 3.1.0 info: title: ClarityQ API description: ClarityQ API, authenticated via API keys. version: 1.0.0 servers: - url: https://api.clarityq.ai description: Production security: - ApiKeyAuth: [] paths: /api/v1/products/{product_id}/usage/prompts: get: tags: - API summary: Get prompt usage description: >- Return prompt usage for the organization that owns the given product as flat count buckets, always grouped by product. Use the repeatable breakdown_by parameter to control dimensions (user, origin, date); by default counts are broken down by origin, aggregated over the whole window. The API key authorizes its own product, but the response covers every product in that organization so a single key gives org-wide visibility. Counts cover all prompt origins unless the origin parameter is supplied. Requires prompt usage tracking to be enabled for the organization. Dates are optional and default to the last 30 days. operationId: get_prompt_usage_api_v1_products__product_id__usage_prompts_get parameters: - name: product_id in: path required: true schema: type: string format: uuid title: Product Id - name: start_date in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- First UTC calendar day to include (YYYY-MM-DD). Defaults to 30 days before end_date. title: Start Date description: >- First UTC calendar day to include (YYYY-MM-DD). Defaults to 30 days before end_date. - name: end_date in: query required: false schema: anyOf: - type: string format: date - type: 'null' description: >- Last UTC calendar day to include, inclusive (YYYY-MM-DD). Defaults to today (UTC). title: End Date description: >- Last UTC calendar day to include, inclusive (YYYY-MM-DD). Defaults to today (UTC). - name: breakdown_by in: query required: false schema: type: array items: $ref: '#/components/schemas/PromptUsageBreakdownDimension' description: >- Dimensions to break the counts down by (repeatable): user, origin, date. Product is always included. Defaults to origin. default: - origin title: Breakdown By description: >- Dimensions to break the counts down by (repeatable): user, origin, date. Product is always included. Defaults to origin. - name: product_ids in: query required: false schema: anyOf: - type: array items: type: string format: uuid - type: 'null' description: >- Restrict to these products in the org (repeatable). Defaults to all products. title: Product Ids description: >- Restrict to these products in the org (repeatable). Defaults to all products. - name: user_ids in: query required: false schema: anyOf: - type: array items: type: string format: uuid - type: 'null' description: Restrict to these users (repeatable). Defaults to all users. title: User Ids description: Restrict to these users (repeatable). Defaults to all users. - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter to users whose email or full name contains this text. title: Search description: Filter to users whose email or full name contains this text. - name: origin in: query required: false schema: anyOf: - $ref: '#/components/schemas/PromptUsageOrigin' - type: 'null' description: >- Restrict to a single prompt origin (APP, SLACK, API_KEY). Defaults to all origins. title: Origin description: >- Restrict to a single prompt origin (APP, SLACK, API_KEY). Defaults to all origins. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PromptUsageBreakdownResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PromptUsageBreakdownDimension: type: string enum: - user - origin - date title: PromptUsageBreakdownDimension description: >- Extra dimensions a prompt usage row can be broken down by (product is always included). PromptUsageOrigin: type: string enum: - APP - SLACK - API_KEY title: PromptUsageOrigin description: Channel a prompt was sent through, used to filter the usage export. PromptUsageBreakdownResponse: properties: start_date: type: string format: date title: Start Date description: First UTC calendar day included in the window (YYYY-MM-DD) end_date: type: string format: date title: End Date description: Last UTC calendar day included in the window, inclusive (YYYY-MM-DD) breakdown_by: items: $ref: '#/components/schemas/PromptUsageBreakdownDimension' type: array title: Breakdown By description: >- Extra dimensions the rows are broken down by (product is always included) total_prompts: type: integer title: Total Prompts description: Total prompts across all rows in the response rows: items: $ref: '#/components/schemas/PromptUsageRow' type: array title: Rows description: >- Prompt-count buckets, one per product and requested dimension combination type: object required: - start_date - end_date - total_prompts title: PromptUsageBreakdownResponse description: >- Org-wide prompt usage for a date window, one row per requested dimension combination. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PromptUsageRow: properties: product_id: type: string format: uuid title: Product Id description: ID of the product the prompts were sent to product_name: type: string title: Product Name description: Display name of the product user_id: anyOf: - type: string format: uuid - type: 'null' title: User Id description: >- ID of the user who sent the prompts (present when breakdown_by includes 'user') user_email: anyOf: - type: string - type: 'null' title: User Email description: >- Email of the user who sent the prompts (present when breakdown_by includes 'user') origin: anyOf: - $ref: '#/components/schemas/PromptUsageOrigin' - type: 'null' description: >- Channel the prompts were sent through (present when breakdown_by includes 'origin') date: anyOf: - type: string format: date - type: 'null' title: Date description: >- UTC calendar day the prompts were sent on (present when breakdown_by includes 'date') prompt_count: type: integer title: Prompt Count description: Number of prompts in this bucket type: object required: - product_id - product_name - prompt_count title: PromptUsageRow description: >- A single prompt-count bucket; dimension fields beyond product are present only when requested. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key obtained from the ClarityQ dashboard. ````