List Tags
Every tag defined for a domain, with per-tag prompt usage counts — the lookup you use to turn tag names into tag_ids before adding a prompt.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/tags?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/tags",
params={"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3"},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
# Resolve a name to its id for the add-prompt call.
tags_by_name = {t["name"].lower(): t["id"] for t in resp.json()["data"]}
branded_id = tags_by_name["branded"]
print(branded_id)
const url = new URL("https://api.aiclicks.io/api/v1/tags");
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();
const byName = Object.fromEntries(data.map((t) => [t.name.toLowerCase(), t.id]));
console.log(byName["branded"]);
{
"data": [
{
"id": "a1b2c3d4-1111-4aaa-8bbb-000000000001",
"name": "Branded",
"color": { "id": "slate", "key": "slate", "label": "Slate", "hex_bg": "#f1f5f9", "hex_text": "#334155", "sort_order": 1 },
"count": 18,
"auto_assigned": false
},
{
"id": "a1b2c3d4-1111-4aaa-8bbb-000000000004",
"name": "Commercial",
"color": { "id": "amber", "key": "amber", "label": "Amber", "hex_bg": "#fef3c7", "hex_text": "#b45309", "sort_order": 4 },
"count": 22,
"auto_assigned": false
},
{
"id": "a1b2c3d4-1111-4aaa-8bbb-000000000003",
"name": "Informational",
"color": { "id": "blue", "key": "blue", "label": "Blue", "hex_bg": "#dbeafe", "hex_text": "#1d4ed8", "sort_order": 3 },
"count": 30,
"auto_assigned": false
},
{
"id": "a1b2c3d4-1111-4aaa-8bbb-000000000002",
"name": "Non-Branded",
"color": { "id": "gray", "key": "gray", "label": "Gray", "hex_bg": "#f3f4f6", "hex_text": "#374151", "sort_order": 2 },
"count": 41,
"auto_assigned": true
},
{
"id": "a1b2c3d4-1111-4aaa-8bbb-000000000005",
"name": "Transactional",
"color": { "id": "red", "key": "red", "label": "Red", "hex_bg": "#fee2e2", "hex_text": "#b91c1c", "sort_order": 5 },
"count": 9,
"auto_assigned": true
}
],
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"generated_at": "2026-08-18T10: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."
}
Returns the domain's tag catalog: one row per tag with its display color and how many prompts currently carry it. Use it to resolve human-readable tag names ("Branded", "Commercial") into the tag_ids that `` expects — the write endpoint takes ids, not names, so this is the read you call first.
The list is sorted by tag name (case-insensitive). Every domain is seeded with five defaults — Branded, Non-Branded, Informational, Commercial, Transactional — so this endpoint is rarely empty.
domain_id is a required query parameter. Use `` 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. Find domains via ``. Omitting this returns 400.
Response
One row per tag defined on the domain, sorted by name (case-insensitive).
Echo of the requested domain.
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. A newly created tag, or a count that changes as you tag prompts, appears after the TTL expires.
Errors
domain_id query parameter missing. Body points you at /api/v1/domains.
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
A domain with no tags (all defaults deleted) returns a successful 200 with an empty list:
{
"data": [],
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"generated_at": "2026-08-18T10:00:11.218Z"
}