Skip to content
MentionBird.ai
Browse the documentation

Get Owned vs Earned Share

How citations split between domains the brand owns, competitor-owned domains and earned third-party coverage. The filters narrow it the way the dashboard's sources page does.

GET /sources/owned-share

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.
llm_provider string Filter to one AI platform.
One of: openai claude gemini perplexity grok
query_tag string Filter to one tag slug.
brand_prompt_id string Limit to one prompt — token from listQueries.
source_type string Site category — see listCitationTags.
content_type string Page category — see listCitationTags.
search string Substring match on domain, URL or page title.

Example request

curl -H "Authorization: Bearer $MENTIONBIRD_API_KEY" \
  "https://api.mentionbird.ai/api/v1/sources/owned-share?brand=Acme"

Example response

Recorded from a live call against a demo workspace, so the shape is exactly what the endpoint returns.

{
  "competitor": 0,
  "competitor_pct": 0.0,
  "earned": 2,
  "earned_pct": 100.0,
  "filters_applied": {
    "brand": "Acme",
    "brand_prompt_id": null,
    "content_type": null,
    "end_date": "2026-11-18",
    "llm_provider": null,
    "query_tag": null,
    "search": null,
    "source_type": null,
    "start_date": "2026-10-20"
  },
  "no_owned_domains_declared": false,
  "total": 2,
  "yours": 0,
  "yours_pct": 0.0
}

Responses

200
Ownership breakdown.
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.