Skip to main content
GET
Get prompt usage
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), usage_type and task (both below) and date (UTC calendar day). 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.
Example request
Example response

Attributing usage to scheduled tasks

origin tells you how a prompt arrived — from the app, from Slack, or through an API key. It does not tell you what produced it: a scheduled task runs under its owner and is reported as APP, indistinguishable from that person typing a question. Break down by usage_type instead to attribute usage to the channel that produced it: Combine it with date or user as usual, and add the usage_type query parameter to narrow to a single value. Those seven are the values that carry prompts; BACKGROUND exists as a usage type but is never a billable prompt, so filtering on it returns 422 rather than an empty response.
Example request
Example response

One row per scheduled task

usage_type tells you how much came from scheduled tasks. breakdown_by=task tells you which task: one row each, carrying the task’s own id and name.
Example request
Example response
A task’s rows are keyed on the task itself, not on the title of the conversation each run happened to create, so renaming a conversation — or one task running nightly — still reports one row per task. Combine with date or user to split it further. task_id matches the id of the task in the Tasks API, so these counts join straight onto your own list of scheduled tasks.
breakdown_by=task covers scheduled task runs only — nothing else has a task to be attributed to. A usage_type filter that contradicts that (anything other than TASK) returns 422.
origin cannot be combined with usage_type or task in one request — they are measured separately and their totals are not guaranteed to match to the prompt. Asking for both returns 422.

Which number to read

A usage_type or task breakdown states your organization’s billing unit in unit:
  • PROMPTS — read prompt_count on each row and total_prompts on the response.
  • CQT — read cqt on each row and total_cqt on the response. Rows still carry prompt_count, but CQT is what you are billed on. Usage from before your organization moved to CQT billing is never included, so a window that starts earlier is reported from the switch date onwards and the response echoes the adjusted start_date.
cqt and total_cqt are omitted entirely for organizations billed in prompts.

Authorizations

X-API-Key
string
header
required

API key obtained from the ClarityQ dashboard.

Path Parameters

product_id
string<uuid>
required

Query Parameters

start_date
string<date> | null

First UTC calendar day to include (YYYY-MM-DD). Defaults to 30 days before end_date.

end_date
string<date> | null

Last UTC calendar day to include, inclusive (YYYY-MM-DD). Defaults to today (UTC).

breakdown_by
enum<string>[]

Dimensions to break the counts down by (repeatable): user, origin, usage_type, task, date. Product is always included. Defaults to origin. origin cannot be combined with usage_type or task. task covers scheduled task runs only.

Extra dimensions a prompt usage row can be broken down by (product is always included).

Available options:
user,
origin,
usage_type,
task,
date
product_ids
string<uuid>[] | null

Restrict to these products in the org (repeatable). Defaults to all products.

user_ids
string<uuid>[] | null

Restrict to these users (repeatable). Defaults to all users.

search
string | null

Filter to users whose email or full name contains this text.

origin
enum<string> | null

Restrict to a single prompt origin (APP, SLACK, API_KEY). Defaults to all origins. Channel a prompt was sent through, used to filter the usage export.

Available options:
APP,
SLACK,
API_KEY,
EMBED,
DIAGNOSIS
usage_type
enum<string> | null

Restrict to a single usage type (TASK, ASK_ANYTHING, BUILDER, API, SLACK, EMBED, DIAGNOSIS). Requires breakdown_by=usage_type. Defaults to all types. BACKGROUND carries no prompts and is rejected. Closed, ordered enum. The FE hard-codes column order and colors from it.

Available options:
ASK_ANYTHING,
BUILDER,
EMBED,
SLACK,
API,
TASK,
DIAGNOSIS,
BACKGROUND

Response

Successful Response

Org-wide prompt usage for a date window, one row per requested dimension combination.

start_date
string<date>
required

First UTC calendar day included in the window (YYYY-MM-DD)

end_date
string<date>
required

Last UTC calendar day included in the window, inclusive (YYYY-MM-DD)

total_prompts
integer
required

Total prompts across all rows in the response

breakdown_by
enum<string>[]

Extra dimensions the rows are broken down by (product is always included)

Extra dimensions a prompt usage row can be broken down by (product is always included).

Available options:
user,
origin,
usage_type,
task,
date
unit
enum<string> | null

The org's billing unit. CQT orgs should read cqt; prompt-billed orgs read prompt_count. Stated on a usage_type breakdown only

Available options:
PROMPTS,
CQT
total_cqt
integer | null

Total CQT across all rows. Present only for an org billed in CQT

rows
PromptUsageRow · object[]

Prompt-count buckets, one per product and requested dimension combination