ai_visibility_trend
AI answer-engine (ChatGPT/Perplexity/Gemini/AI Mode) citations — NOT Google's on-SERP AI Overviews (use competitive_trends/competitive_overview for those). Use ONLY for OVER-TIME / trend questions (a time series). Citations, share of voice and positive sentiment bucketed by day/week/month/quarter for one tracker, optionally for a single AI platform or search intent. Use for "is our AI visibility going up or down?" / "AI citations over the last 3 months". If tracker is omitted, one tracker is auto-selected; multiple trackers return a picker without querying metrics. For the current snapshot use ai_visibility_citation_audit; for per-competitor breakdown use ai_visibility_competitors.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"date_range": "<date_range>"
},
"name": "ai_visibility_trend"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| brand | No | Restrict to BRANDED ("Yes") or NON-BRANDED ("No") prompts — branded prompts (e.g. "example-brand login") behave very differently from category prompts (e.g. "best web hosting"); a blended number mixes them. Omit for all prompts. | |
| device | No | Optional device filter. Values are normalized to uppercase, e.g. DESKTOP or MOBILE. Applied on the same tracker-scoped AI visibility reads as country. Overview and citation audit require a tracker. If the underlying data has no device filter, the tool says so and returns no totals. | |
| intent | No | Restrict to one search intent, e.g. "Informational" / "Transactional". | |
| metric | No | DISPLAY-ONLY card metric (does not change the query): cit=citations (default), sov=share of voice, men=mentions, sen=sentiment. | |
| country | No | Optional country filter, e.g. "USA". Applied on tracker-scoped AI visibility reads (overview, citation audit, competitors, trend, and drilldown). Overview and citation audit require a tracker. The geography drilldown tab groups rows by country instead of filtering them. If the underlying data has no country filter, the tool says so and returns no totals. | |
| tracker | No | AI Visibility tracker (unified segment id), e.g. "AI Tracker". If omitted, the only ACTIVE tracker is auto-selected; multiple trackers (or only paused ones) return a picker without querying. A paused tracker (collection stopped on its end date) is honored when named explicitly, and the result carries trackerStatus "paused" — report it as historical, not current. | |
| platform | No | Restrict to one AI platform, e.g. "chatgpt" / "gemini" (platform key). | |
| chart_view | No | Card perspective: "platforms" (default, per-platform lines) or "allmetrics" (all four metrics, indexed) are display-only over the same per-platform series; "competitors" CHANGES the query — it returns a per-competitor over-time series (competitorSeries) from competitor_details (C6). | |
| date_range | Yes | Explicit date range, e.g. "2026-05-01 to 2026-05-31". Both endpoints are INCLUSIVE — the END day is covered (a 7-day range = 7 days). Quattr weeks run Sunday–Saturday; for "last week" use the most recent complete Sun–Sat span. | |
| value_mode | No | DISPLAY-ONLY card value mode (does not change the query): "pct" (default, percentage) or "total" (raw count). | |
| granularity | No | Trend bucket size: day, week (default), month or quarter. | |
| comparison_range | No | Explicit comparison range for period-over-period, e.g. "2026-04-01 to 2026-04-30". Adds per-row deltas (delta + deltaPct) for the metrics; never changes which rows return (deltas are left-joined onto the selected period). |