Skip to content
MentionBird.ai
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.