Get prompt usage

curl --request GET \
  --url https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "start_date": "2023-12-25",
  "end_date": "2023-12-25",
  "total_prompts": 123,
  "breakdown_by": [],
  "rows": [
    {
      "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_name": "<string>",
      "prompt_count": 123,
      "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "user_email": "<string>",
      "date": "2023-12-25"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

API Reference

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.

GET

api

products

{product_id}

usage

prompts

Get prompt usage

curl --request GET \
  --url https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts"

headers = {"X-API-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts")
  .header("X-API-Key", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.clarityq.ai/api/v1/products/{product_id}/usage/prompts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "start_date": "2023-12-25",
  "end_date": "2023-12-25",
  "total_prompts": 123,
  "breakdown_by": [],
  "rows": [
    {
      "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "product_name": "<string>",
      "prompt_count": 123,
      "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "user_email": "<string>",
      "date": "2023-12-25"
    }
  ]
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

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.

Example request

GET /api/v1/products/{product_id}/usage/prompts
    ?start_date=2026-05-01&end_date=2026-05-31
    &breakdown_by=user&breakdown_by=origin

Example response

{
  "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
    }
  ]
}

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, date. Product is always included. Defaults to origin.

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

Available options:

user,

origin,

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.

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

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,

date

rows

PromptUsageRow · object[]

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

Show child attributes

Get last completed task run summary

Get Started

Data Warehouse Connections

Context Layer

Building the Context Layer

Ask Anything

Dashboards

Automations

Integrations

Administration

API Reference

Get Prompt Usage

Authorizations

Path Parameters

Query Parameters

Response