APIReferenceAnalytics
Category date-range analytics
Category-scoped aggregated metrics / share-of-voice / sources / platforms / coverage over a date range. Same block set + window params as the brand analytics endpoint.
GET
/api/categories/{category_id}/analytics/AuthorizationBearer <token>
Personal Access Token (create one from Settings -> API Keys in the dashboard). Send as Authorization: Bearer gr_live_.... An X-API-Key: gr_live_... header (see the apiKeyAuth scheme) is accepted as an equivalent alternative — send ONE of the two, not both.
In: header
Path Parameters
category_id*integer
Query Parameters
end?string
YYYY-MM-DD — required with range=custom, otherwise rejected.
range?string
Rolling window preset, all (no upper bound on history), or custom (requires start + end). Default 30d.
Value in
- "30d"
- "7d"
- "90d"
- "all"
- "custom"
start?string
YYYY-MM-DD — required with range=custom, otherwise rejected.
Response Body
application/json
curl -X GET "https://example.com/api/categories/0/analytics/"{ "window": { "range": "30d", "start": "2026-06-26T00:00:00+00:00", "end": "2026-07-26T00:00:00+00:00", "asOf": "2026-07-26T00:00:00+00:00", "timezone": "America/New_York", "selection": { "kind": "rolling", "preset": "30d", "startDate": null, "endDate": null }, "previous": { "start": "2026-05-27T00:00:00+00:00", "end": "2026-06-26T00:00:00+00:00" }, "bounds": { "earliestObservationAt": "2026-01-14T09:00:00+00:00" } }, "metrics": { "scope": "historical_observation", "label": "Selected period", "sampleCount": 540, "mentionRate": { "value": 62, "previousValue": 55, "delta": 7, "suppressedReason": null }, "avgRank": { "value": 2.1, "previousValue": 2.4, "delta": -0.3, "suppressedReason": null }, "sentiment": { "positive": 210, "neutral": 240, "negative": 90, "previous": null } }, "shareOfVoice": { "scope": "historical_observation", "label": "Selected period", "visible": [ { "id": "sov-412-you", "categoryId": "412", "name": "Acme Co", "mentions": 335, "averageRank": 1, "score": null, "isUserBrand": true, "sourceBreakdown": [], "share": 62, "previousShare": 55, "shareDelta": 7, "shareDeltaSuppressedReason": null } ], "hidden": [] }, "sources": { "totalDomains": 118, "totalCitations": 402, "items": [ { "domain": "reddit.com", "count": 61, "share": 15.2, "previousShare": 12, "shareDelta": 3.2, "shareDeltaSuppressedReason": null, "urlCount": 12 } ] }, "platforms": { "scope": "historical_observation", "label": "Selected period", "apiPlatforms": [ { "model": "chatgpt", "modelLabel": "ChatGPT", "score": 640, "mentionRate": 64, "totalAnswers": 90 } ], "surfacePlatforms": [ { "surface": "perplexity_ui", "surfaceLabel": "Perplexity (Consumer UI)", "score": 580, "mentionRate": 58, "totalSamples": 45 } ] }, "coverage": { "observationMethodology": "sample_v1", "comparableFrom": "2026-04-23T00:00:00+00:00", "usableSampleCount": 540, "legacyFallbackCount": 0, "excludedMethodologyCount": 0, "excludedErrorCount": 3, "excludedEmptyCount": 1, "excludedNoResultCount": 0, "unreconstructableLegacyAnswerCount": 0, "sampleWeightTotal": 540, "promptCoverageCount": 18 }}