Sentiment Overview
Positive vs. negative sentiment split for how AI answers talk about a tracked domain.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/sentiment/overview?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&days=30' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/sentiment/overview",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
d = resp.json()["data"]
print(f"{d['positive_percent']}% positive across {d['total_mentions']} mentions")
const url = new URL("https://api.aiclicks.io/api/v1/sentiment/overview");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.set("days", "30");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
console.log(`${data.positive_percent}% positive across ${data.total_mentions} mentions`);
{
"data": {
"positive_percent": 75.0,
"negative_percent": 25.0,
"total_mentions": 80
},
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all",
"generated_at": "2026-06-17T10: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." }
How LLMs feel about your brand right now, as a single split. Every sentiment theme extracted from AI answers in the window is tagged positive or negative; this endpoint returns the share of each plus the total number of mentions those themes cover.
Unlike the time-series endpoints, data here is a flat object — not a list.
domain_id is a required query parameter. Use GET /api/v1/domains to discover which domains the calling key can access.
Sentiment is a paid feature. The endpoint returns 403 unless the domain's team is on a Pro, Business, or Enterprise plan — in addition to the usual API-access requirement.
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.
Look-back window in days, 1–365. Defaults to 30. Counted as an exact window (today - days + 1), not snapped to buckets.
Restrict to a single AI channel by generic name — ChatGPT, Perplexity, Gemini, AI Overviews, Claude, Grok, Microsoft Copilot. Defaults to all (every channel). Raw model identifiers (e.g. gpt-4o-search) are also accepted for backwards compatibility. See Models.
Response
The sentiment split. A flat object — no items array.
Share of themes tagged positive, 0–100, rounded to one decimal. positive_count / (positive_count + negative_count) * 100.
Share of themes tagged negative, 0–100, rounded to one decimal. positive_percent + negative_percent sums to 100 (barring rounding) whenever any themes exist.
Total occurrences across all themes in the window — the sum of each theme's occurrences. Not the theme count; a single theme can carry many mentions.
Echo of the requested domain.
Echo of the requested window.
Echo of the requested model filter (all when unset).
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, days, model). Newly completed analyses appear after the TTL expires.
How sentiment is computed
Sentiment is derived from themes, not individual responses:
- During analysis, recurring topics in the AI answers about your brand are clustered into named themes.
- Each theme is classified
positiveornegative, and carries anoccurrencescount. - This endpoint counts positive vs. negative themes in the window and expresses each as a percentage;
total_mentionssums the occurrences.
To see the themes themselves, use GET /api/v1/sentiment/themes. For the day-by-day trend, use GET /api/v1/sentiment/time-series.
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, your allowed_domains allowlist excludes it, or the team's plan doesn't include sentiment (requires Pro, Business, or Enterprise).
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 no sentiment themes exist in the window, the response is a successful 200 with zeroes:
{
"data": { "positive_percent": 0.0, "negative_percent": 0.0, "total_mentions": 0 },
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"days": 30,
"model": "all",
"generated_at": "2026-06-17T10:00:11.218Z"
}