List Tracked Competitors
Every competitor tracked for a domain — dedicated brands you added and auto-discovered ones — optionally filtered by dedicated/active.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/competitors?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&is_dedicated=true&active=true' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/competitors",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"is_dedicated": True,
"active": True,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for c in resp.json()["data"]:
print(f"{c['name']:<24} {c['website']:<28} dedicated={c['is_dedicated']} active={c['active']}")
const url = new URL("https://api.aiclicks.io/api/v1/competitors");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.set("is_dedicated", "true");
url.searchParams.set("active", "true");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
for (const c of data) console.log(c.name, c.website, c.is_dedicated, c.active);
{
"data": [
{
"id": "f6a7b8c9-3333-4eee-8fff-000000000001",
"created_at": "2026-05-02T14:21:07.882Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Acme Rival",
"website": "acmerival.com",
"is_dedicated": true,
"active": true,
"updated_at": "2026-07-19T09:03:44.120Z",
"variations": ["Acme", "AcmeRival Inc"]
},
{
"id": "f6a7b8c9-3333-4eee-8fff-000000000002",
"created_at": "2026-06-11T08:55:31.010Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"name": "Beacon Tools",
"website": "beacontools.io",
"is_dedicated": true,
"active": true,
"updated_at": "2026-06-11T08:55:31.010Z",
"variations": []
}
],
"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 competitor set as stored: one row per competitor, both the dedicated brands you added by hand (is_dedicated: true) and the discovered ones the models surfaced in answers (is_dedicated: false). This is the raw tracking list — no visibility or share-of-voice metrics. For ranked performance use GET /api/v1/brand-rankings; for untracked brands worth adding use GET /api/v1/competitor-discovery.
Filter with is_dedicated and active to narrow the set — e.g. is_dedicated=true&active=true returns exactly the dedicated competitors currently counting against your plan limit.
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. Find domains via GET /api/v1/domains. Omitting this returns 400.
When set, returns only competitors with this flag. true = brands you added by hand; false = auto-discovered from model answers. Omit to return both.
When set, returns only competitors with this state. true = actively tracked; false = suggested but not yet tracked. Omit to return both.
Response
One row per competitor on the domain matching the filters, as stored.
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, is_dedicated, active) filter combination. A competitor added via POST /api/v1/competitors busts this cache immediately, so the new row shows up on the next list call.
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 competitors matching the filters returns a successful 200 with an empty list:
{
"data": [],
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"generated_at": "2026-08-18T10:00:11.218Z"
}