Prompt Metrics
Get each tracked prompt with its metrics for the window: visibility, mentions, citations, position, answers, topics and tags. You can filter, sort and paginate the list.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/prompt-metrics?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&sort_by=visibility&sort_dir=asc&size=50' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/prompt-metrics",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"topic_ids": ["d4c3b2a1-0000-4aaa-8bbb-000000000010"],
"sort_by": "visibility",
"sort_dir": "asc",
"size": 50,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
# The 10 prompts with the lowest visibility in one topic.
for row in resp.json()["data"]["items"][:10]:
print(f'{row["visibility"]:5.1f}% {row["text"]}')
const url = new URL("https://api.aiclicks.io/api/v1/prompt-metrics");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.set("sort_by", "mentions");
url.searchParams.append("tag_ids", "a1b2c3d4-1111-4aaa-8bbb-000000000004");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
console.log(data.pagination.total_count, data.items[0]);
{
"data": {
"items": [
{
"id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"text": "best inventory software for small business",
"estimated_search_volume": 1900,
"responses": 135,
"mentions": 71,
"citations": 1731,
"visibility": 52.6,
"avg_position": 2.0,
"topics": ["Inventory Software"],
"tags": ["Commercial", "Non-Branded"]
},
{
"id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"text": "how to set reorder points",
"estimated_search_volume": 0,
"responses": 137,
"mentions": 0,
"citations": 1713,
"visibility": 0.0,
"avg_position": null,
"topics": ["Inventory Basics"],
"tags": ["Informational"]
}
],
"pagination": {
"current_page": 1,
"per_page": 100,
"total_count": 2,
"total_pages": 1,
"has_next": false,
"has_prev": false,
"last_page": true
}
},
"generated_at": "2026-11-09T05:50:43.155Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "API key not authorized for this domain."
}
{
"detail": "Domain not found"
}
{
"detail": "Too many requests. Please try again later."
}
This endpoint returns each tracked prompt of a domain with its totals for the window. Each row has the visibility, mentions, citations, average position, the number of answers, the search volume, the topics and the tags.
Use this endpoint to make a table of prompts. For example, sort by visibility in ascending order to find the prompts where your brand is weakest. To see a daily series for each prompt, use GET /api/v1/prompt-statistics-time-series.
The list includes prompts with no answers in the window. Their metrics are zero.
The domain_id parameter is required. To get domain IDs, use GET /api/v1/domains.
Authorizations
Your API key in the format Bearer ak_live_<your-key>. To make a key, go to Settings → Developers in the dashboard.
An optional UUID to find the request in logs. If you do not send one, the server makes one and returns it.
Query parameters
The UUID of the domain. To get it, use GET /api/v1/domains.
Topic UUIDs from GET /api/v1/topics. To send more than one, repeat the parameter. The list keeps only prompts in these topics.
Tag UUIDs from GET /api/v1/tags. To send more than one, repeat the parameter. If you also send topic_ids, the list keeps a prompt that matches either filter.
One AI channel by its generic name, or all. Examples: ChatGPT, Perplexity, Gemini, AI Overviews, AI Mode, Claude, Microsoft Copilot, Grok. The default is all.
The number of days to look back from today, from 1 to 365. The server uses the exact value. The default is 30.
The first day of a fixed window, in the format YYYY-MM-DD. Send it with end_date. Together, they replace days. The maximum range is 365 days.
The last day of a fixed window, in the format YYYY-MM-DD. The window includes this day. Send it with start_date.
The column to sort by: visibility, mentions, citations, avg_position, responses or estimated_search_volume. Prompts with no value are always last. The default is visibility.
The sort direction: asc or desc. The default is desc.
The page number. The first page is 1. The default is 1.
The number of prompts on each page, from 1 to 500. The default is 100.
If true, the server does not use the cache and calculates the result again. The default is false.
Response
The prompts and the pagination data.
One row for each prompt, in the order that sort_by and sort_dir set.
The page data: current_page, per_page, total_count, total_pages, has_next, has_prev and last_page. total_count is the number of prompts after the filters.
The domain that you requested.
The window that you requested.
The model filter that you requested. If you did not send one, the value is all.
The ISO-8601 time when the server made or cached this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS. If you send fresh=true, the value is REFRESH. |
X-Request-Id | The unique ID of the request. If you sent one, the server returns the same value. |
X-RateLimit-Limit | The maximum number of requests each minute for this key. |
X-RateLimit-Remaining | The number of requests that remain in the current minute. |
X-RateLimit-Reset | The Unix time in seconds when the window starts again. |
Caching
The server keeps each response in the cache for 1 hour. The cache key includes all the query parameters. A new prompt, or a new tag on a prompt, shows after the cache expires. To get it at once, send fresh=true.
Errors
A date is not in the format YYYY-MM-DD, start_date is after end_date, or the range is longer than 365 days.
The API key is missing, not correct, or revoked.
API access is off for the team, or the domain is in a team that your key cannot access.
The domain_id is not valid, does not exist, or is not in your team.
domain_id is missing, or sort_by, sort_dir, days, page or size has a value that is not permitted.
You sent too many requests. Read the Retry-After header to know how long to wait.
Empty result
If no prompts match the filters, the server returns 200 with an empty list:
{
"data": {
"items": [],
"pagination": { "current_page": 1, "per_page": 100, "total_count": 0, "total_pages": 0, "has_next": false, "has_prev": false, "last_page": true }
},
"generated_at": "2026-11-09T05:50:43.155Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all"
}