Browse the documentation
Get Citation Breakdown
The kinds of sources AI platforms cite when answering this brand's prompts: those citations grouped by source_type (kind of site), content_type (kind of page) or url_status (link health).
GET
/citations/breakdown
Query parameters
| Name | Type | Description |
|---|---|---|
| brand required | string | Tracked brand name, exactly as returned by listTrackedBrands. |
| start_date | string | ISO start date (YYYY-MM-DD). Defaults to 30 days ago. The range may span at most 365 days; a longer one is a 400. |
| end_date | string | ISO end date (YYYY-MM-DD). Defaults to today. |
| dimension |
string
default source_type |
What to group the citations by.
One of: source_type
content_type
url_status
|
| brand_prompt_id | string | Limit to one prompt — token from listQueries. |
| query_tag | string | Filter to one tag slug. |
| llm_provider | string |
Filter to one AI platform.
One of: openai
claude
gemini
perplexity
grok
|
| domain | string | Filter to one domain. |
| source_type | string | Site category — see listCitationTags. |
| content_type | string | Page category — see listCitationTags. |
| url_status | string |
Link health filter.
One of: unknown
alive
dead
redirect
|
Example request
curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
"https://api.mentionbird.ai/api/v1/citations/breakdown?brand=Acme"
Example response
Recorded from a live call against a demo workspace, so the shape is exactly what the endpoint returns.
{
"date_range": {
"days": 30,
"end": "2026-11-18",
"start": "2026-10-20"
},
"filters_applied": {
"brand": "Acme",
"brand_prompt_id": null,
"content_type": null,
"dimension": "source_type",
"domain": null,
"end_date": "2026-11-18",
"llm_provider": null,
"query_tag": null,
"source_type": null,
"start_date": "2026-10-20",
"url_status": null
},
"has_more": false,
"items": [
{
"citation_count": 1,
"share_pct": 100.0,
"tag_description": "Review aggregators and comparison platforms — G2, Capterra, Trustpilot.",
"tag_name": "review_comparison"
}
],
"returned_count": 1,
"total_count": 1
}
Responses
- 200
- Groups ranked by citation_count, each with share_pct of the counts summed over every group. Under source_type and content_type, citations not yet tagged on that dimension are left out of both; under url_status, a link not yet checked counts as unknown. A citation tagged with several page categories counts once under each of them. The domain, source_type, content_type and url_status filters narrow the citations before grouping, and each citation still counts under every category it carries: content_type=listicle with dimension=content_type also returns the other page categories those listicles are tagged with.
- 400
- Validation error — check the message in `error.message`.
- 401
- Unauthorized — missing, invalid or revoked bearer token.
- 403
- Forbidden — the plan lacks API access, the key is read-only, or addTrackedBrand would pass the tracked-brand limit.
- 404
- Not found — the brand, prompt or resource does not exist.
- 405
- Method not allowed.
- 429
- Too many requests — over the key's per-minute or per-day limit. Wait the seconds in the `Retry-After` header, then retry.
- 500
- Internal error — logged; retry is safe for reads.