API reference

Read-only access to your brands and weekly results, for dashboards, spreadsheets and data tools. Available on Growth and Agency plans. Create a key under Settings, API.

Authentication

Send the key as a bearer token. Keys act on behalf of your whole agency, are shown once when created, and can be revoked at any time.

curl https://mentiongrid.app/api/v1/brands \
  -H "Authorization: Bearer rl_live_..."

Endpoints

Request	Returns
`GET /api/v1/brands`	Your brands: id, name, domain, category, region, competitors.
`GET /api/v1/brands/:id/results?week=2026-W44`	Metrics for one week (latest if omitted): mention rate, share of voice, citation share, per-engine rates, competitors, brands discovered, top sources and a 12-week trend.

Example response

{
  "week": "2026-W44",
  "runs": 90,
  "mentionRate": 0.42,
  "shareOfVoice": 0.31,
  "citationShare": 0.08,
  "byEngine": [{ "engine": "openai", "runs": 30, "mentionRate": 0.5 }],
  "competitors": [{ "name": "Acme", "mentions": 41, "rate": 0.46 }],
  "discovered": [{ "name": "Globex", "mentions": 22, "rate": 0.24 }],
  "trend": [{ "week": "2026-W43", "mentionRate": 0.38 }]
}

Limits and errors

120 requests per minute per agency. Over the limit you get 429.
Errors are JSON: { "error": "message", "code": "SNAKE_CASE" } with status 401 (missing or revoked key), 402 (plan does not include the API), 404 (unknown brand) or 429.
Weeks look like 2026-W44.