Query Parameters & Limits
Request parameters#
Only use parameters listed by the endpoint. Unknown parameters are rejected.| Parameter | Meaning |
|---|
| projectId | Authorized project UUID; an API path parameter or MCP argument |
| entityId | Public entity UUID returned by the service |
| responseId | Tracking response ID returned by the response list |
| startDate, endDate | Inclusive business dates in YYYY-MM-DD format; required for statistical queries |
| categoryId | Authorized L3 market UUID from market.categories; identifies a market |
| platforms, regions | Platform/region codes; Tracking accepts up to 20/50 values, Market accepts one of each. Regions use uppercase two-letter codes |
| topicIds, promptIds | Tracking topic/prompt UUIDs; up to 50/100 values |
| brands | Tracking brand domains from the configured comparison set; up to 51 |
| brandIds | Public brand UUIDs in the market comparison set; up to 100 |
| brandId | Single brand for market citations; valid only with population=brand |
| intentIds | L2 intent codes returned by an intent grouping; up to 20 |
| sourceDomain | Exact source domain, without a protocol or path |
| population | Market citations: market (default, whole market) or brand (responses mentioning the selected brand) |
| collectedAfter | Exclusive Tracking ingestion timestamp in ISO 8601 with timezone; not the annotation update time |
| pageSize, cursor | Cursor pagination; pageSize defaults to 20. Omit cursor on the first page |
| limit | Aggregate/ranking row limit; defaults to 50, or 20 for co-mentions |
For arrays, use comma-separated API query values, such as platforms=chatgpt,gemini, and JSON arrays in MCP, such as "platforms":["chatgpt","gemini"]. MCP metric groupBy uses an array; citation/source groupBy is a single string.| Metric endpoint | Supported groupBy combinations |
|---|
| Tracking | brand, date, prompt, platform, region, topic; brand+date, brand+platform, brand+region, brand+topic, brand+prompt, platform+date |
| Market | brand, date, platform, region, intent; brand+date |
Use commas for combined API groupings, such as groupBy=brand,date. Grouping order may be reversed. Without a brand grouping, select at most one brand; the default is the own brand. With a brand grouping, Tracking defaults to configured brands, while Market defaults to Top N plus the own brand and configured competitors.Query rules#
| Rule | Behavior |
|---|
| Dates | Maximum inclusive span: 90 days. Tracking supports retained history. Market/graph start dates must be within the latest 40 UTC dates, including today; end dates allow two days of timezone grace |
| Business day | Tracking uses fixed UTC-4; Market and graph statistics use UTC |
| Pagination | Follow nextCursor with unchanged filters and pageSize; stop when null. Default cursor lifetime: 24 hours. Do not reuse across keys, projects or operations |
| Market responses | At most the first 500 responses per cursor chain, at most 20 per page. This is 25 pages at size 20 or 500 at size 1. The final page returns only the remaining records; truncated=true means more matching data exists beyond the cap |
| Lists | Default pageSize: 20. Maximum: 100 for projects/topics/prompts, 50 for Tracking responses, 20 for market responses |
| Aggregates | limit is not a page size. Citation limit: 100; child/source limit: 50; co-mention limit: 20. Date groupings return the complete series; results above 10000 rows require a smaller query |
| Market scope | Use only configured, authorized L3 markets. ownBrandSegments summarizes the own brand within configured markets; it does not query unconfigured markets. No additional monthly market-access budget applies |
| Entity scope | Limited to the own brand plus two descendant levels and configured competitors plus one level, with at most 50 entities per root/level. A listed UUID does not grant detail access: check detailAccessible. Unauthorized details return 404 |
| Relationships | Direct children only; no recursive pagination. Co-mention does not imply competition |
| Ratios | Values are 0-1; multiply by 100 for percentages. null is unavailable, not zero. Do not sum or re-average row ratios |
| Aggregation | Tracking visibility and related metrics use valid-day means; share of voice is a period ratio. Market visibility deduplicates responses over the period. Follow meta.aggregation/aggregations and denominator |
| Citations | citedResponseCount counts distinct citing responses; citationCount counts occurrences. Tracking domain rates use cited responses as denominator, while URL rates use all responses. Market citation rates use cited responses in the selected population. Graph sources may be sampled; inspect meta.sample |
| Empty data | Lists can be empty and effectiveRange can be null. Check validDays. A null dataAsOf does not imply freshness through today |
Limits and allowances#
API and MCP share backend counters. Team allowances are shared by all team keys and projects. Read effective values and remaining evidence/request allowances from GET /projects/{projectId}.| Limit | Default / scope |
|---|
| Backend frequency | 60 requests/minute per key; 120/minute per team |
| Backend concurrency | 2 requests per key; 4 per team |
| Daily requests | 5000 per team |
| Daily market evidence | 500 returned responses per team; repeated reads also count |
| Entity detail access | Effective per-project daily distinct-entity allowance in limits.entityAccessDailyLimit; shared with console and Preview access. The own brand also counts; revisiting an entity on the same day does not consume another slot |
| MCP entry frequency | 60 HTTP requests/minute per key per instance; 600 total per instance, including protocol requests and invalid-key attempts |
| MCP entry concurrency | 2 per key per instance; 8 total per instance, held until the response stream ends or is canceled |
Authenticated backend attempts can consume request quota even when processing later fails. MCP initialization and tool discovery do not consume backend data-query requests, but they do count against MCP entry limits. Entry counters are local to each process and reset on restart; backend team counters remain shared across instances.Request and evidence daily allowances reset at UTC 00:00. Entity-access allowances reset at fixed UTC-4 midnight and are shared for the project across console, Preview, API and MCP. Replacing a key does not reset these allowances. The 500-record cursor cap and the team's 500-response daily evidence allowance are separate limits.Modified at 2026-11-04 09:44:02
