List Prompts
Returns the prompts (tracked queries) being monitored for a domain.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/prompts?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/prompts",
params={"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3"},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for p in resp.json()["data"]["items"]:
print(p["id"], p["text"])
const url = new URL("https://api.aiclicks.io/api/v1/prompts");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
for (const p of data.items) console.log(p.id, p.text);
{
"data": {
"items": [
{
"id": "21c1f9aa-9b6d-4e3a-8a31-2b0c0e1f2a3b",
"text": "best CRM for small business",
"estimated_search_volume": 8100,
"created_at": "2026-05-04T09:15:02.118Z"
},
{
"id": "32d2e8bb-aa7e-5f4b-9b42-3c1d1f2a3b4c",
"text": "Salesforce vs HubSpot",
"estimated_search_volume": 4400,
"created_at": "2026-04-20T11:02:08.503Z"
}
],
"total": 137,
"page": 1,
"size": 50,
"total_pages": 3
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"page": 1,
"size": 50,
"generated_at": "2026-06-16T10:00:11.218Z"
}
{
"detail": "domain_id query parameter is required. List the domains this key can access with GET /api/v1/domains, then pass ?domain_id=<uuid>."
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "API access is not enabled for this team. Contact support@aiclicks.io."
}
{
"detail": "Domain not found"
}
{
"detail": "Too many requests. Please try again later."
}
A prompt is a question or query you are tracking against the AI search ecosystem for a given domain — the same prompts that drive every analysis run, visibility metric, and citation report. This endpoint returns them in reverse-chronological order (newest first).
domain_id is a required query parameter. Use GET /api/v1/domains to discover which domains the calling key can access.
Authorizations
Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.
Optional UUID for log correlation. If omitted, we generate one and echo it back in the response.
Query parameters
UUID of the domain whose prompts you want. Find domains via GET /api/v1/domains. Omitting this returns 400.
1-indexed page number. Defaults to 1.
Items per page. Defaults to 50. Min 1, max 500.
Response
The list payload.
Array of prompts on this domain.
UUID of the prompt.
The full prompt text, exactly as it is tracked.
Estimated monthly search volume for the prompt. null if not yet computed.
ISO-8601 timestamp of when the prompt was added.
Total prompts on this domain (across all pages).
Current page (1-indexed).
Items in this page.
Total page count. ceil(total / size).
Echo of the requested domain.
Echo of the requested page.
Echo of the requested page size.
ISO-8601 timestamp of when the server produced (or cached) this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT or MISS. Indicates whether the response came from cache. |
X-Request-Id | Unique request id. Echoes incoming if you set one. |
X-RateLimit-Limit | Max requests per minute for this key. |
X-RateLimit-Remaining | Requests remaining in current minute. |
X-RateLimit-Reset | Unix epoch seconds when the window resets. |
Caching
Cached for 1 hour per (domain_id, page, size). Cache entries are not invalidated when prompts are added on the dashboard — fresh writes appear after the TTL expires.
Errors
domain_id query parameter missing. The response body tells the caller to fetch /api/v1/domains first.
Missing, malformed, or revoked API key.
Team's developer_access flag is off, the domain belongs to a team your API key is not scoped to, or your allowed_domains allowlist excludes it.
domain_id is malformed, does not exist, or your user is not a member of its team.
Rate limit exceeded. Inspect the Retry-After header for how long to wait.
Empty result
If the domain has no prompts yet, the response is a successful 200 with an empty list:
{
"data": { "items": [], "total": 0, "page": 1, "size": 50, "total_pages": 1 },
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"page": 1,
"size": 50,
"generated_at": "2026-06-16T10:00:11.218Z"
}