Skip to content
MentionBird.ai
Browse the documentation

List Citations

Individual cited URLs with page metadata, for detailed source analysis.

GET /citations

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.
end_date string ISO end date (YYYY-MM-DD). Defaults to today.
domain string Filter to one domain.
search string Substring match on domain, URL or page title.
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
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
include_extras boolean
default False 		Include per-domain extracted metadata.
limit integer
default 20 		Max rows (default 20, max 100).
offset integer
default 0 		Rows to skip — the cursor for reading past `limit`. Default 0. While `has_more` is true, repeat with offset advanced by `limit`.

Example request

curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://app.mentionbird.ai/api/v1/citations?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-09-24",
    "start": "2026-08-26"
  },
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": null,
    "content_type": null,
    "domain": null,
    "end_date": "2026-09-24",
    "include_extras": false,
    "limit": 20,
    "llm_provider": null,
    "offset": 0,
    "query_tag": null,
    "search": null,
    "source_type": null,
    "start_date": "2026-08-26",
    "url_status": null
  },
  "has_more": false,
  "items": [
    {
      "canonical_url": "",
      "citation_count": 1,
      "content_type_tags": [
        "Listicle"
      ],
      "domain": "g2.com",
      "domain_authority": 94,
      "html_title": "",
      "last_seen": "2026-09-24T13:48:50.957069+00:00",
      "meta_description": "",
      "metadata_status": "pending",
      "og_description": "",
      "og_image": "",
      "og_title": "",
      "page_title": "Best CRM Software 2026",
      "providers": [
        "openai"
      ],
      "source_type_tags": [
        "review_comparison"
      ],
      "url": "https://www.g2.com/categories/crm",
      "url_status": "unknown"
    },
    {
      "canonical_url": "",
      "citation_count": 1,
      "content_type_tags": [],
      "domain": "youtube.com",
      "domain_authority": null,
      "html_title": "How to Choose a CRM",
      "last_seen": "2026-09-24T13:48:50.957069+00:00",
      "meta_description": "",
      "metadata_status": "ok",
      "og_description": "",
      "og_image": "",
      "og_title": "",
      "page_title": "How to Choose a CRM",
      "providers": [
        "openai"
      ],
      "source_type_tags": [
        "social"
      ],
      "url": "https://youtube.com/watch?v=aqz-KE-bpKQ",
      "url_status": "unknown"
    }
  ],
  "returned_count": 2,
  "total_count": 2
}

Responses

200
Citations with page metadata. Each row's domain_authority is a 0-100 site-authority score for the row's domain, not the page. 0 is a real measured score meaning genuinely low authority; null is unknown - not yet looked up, or the lookup failed - so leave that row out of authority comparisons.
400
Validation error — check the message in `error.message`.
401
Unauthorized — missing, invalid or revoked bearer token.
403
Forbidden — plan lacks API access, or key is read-only.
404
Not found — the brand, prompt or resource does not exist.
405
Method not allowed.
500
Internal error — logged; retry is safe for reads.