Pagination & filtering

Every list endpoint follows the same conventions.

Pagination

Top-level page and page_size query params:

curl "https://core.cognizo.ai/api/v2/brands/BRAND_ID/prompts?page=2&page_size=50" \
  -H "X-API-KEY: YOUR_API_KEY"

On most list endpoints — prompts, citations, ads, advertisers — page_size defaults to 25 and caps at 100. Opportunities default to 50 and cap at 500. A value above the cap is clamped, not rejected, so asking for 1,000 returns the maximum. The meta block reports what you actually received:

{
  "data": [ ],
  "meta": { "page": 2, "page_size": 50, "total_items": 240, "total_pages": 5 }
}

page + page_size is the only pagination contract — limit, offset, skip, and per_page are not accepted.

list_brands is the exception: send neither parameter and it returns every brand your organization owns, with no meta block. Send either one and it paginates, defaulting to 50 per page. list_brand_ad_opportunity_lists doesn’t paginate at all — a brand has a handful of strategy lists, so it returns all of them with no meta block.

Sorting

sort takes a comma-separated list of keys; prefix a key with - for descending. Unknown keys are ignored and the endpoint falls back to its documented default — a typo silently gives you the default order rather than an error, so check the key names.

?sort=-visibility,prompt

Each endpoint whitelists its own keys; the reference page lists them. The common ones:

Endpoint	Sort keys
`list_brand_prompts`	`prompt`, `topic`, `region`, `visibility`, `sentiment`, `volume`, `competitors`, `last_run`, `citation_share`
`list_brand_citations_domains`	`citation_count`, `brand_citation_count`, …
`list_brand_ads`	`appearances`, `prompts`, `last_seen`
`list_brand_advertisers`	`appearances`, `prompts`, `ads`, `advertiser`, `last_seen`
`list_brand_ad_opportunities`	`score`, `type`, `intent`, `difficulty` (`kd`), `volume`, `cpc`, `text` — defaults to `-score`

Filtering

Filters live under filter[…] bracket notation:

List filters end in _ids and are plural — repeat the key or pass a CSV:

?filter[topic_ids][]=a&filter[topic_ids][]=b
?filter[topic_ids]=a,b

Enum lists are plural too: ?filter[page_types][]=article
Single-value filters are scalar: ?filter[citation_domain]=example.com
Free-text search is always ?filter[query]=… (never ?search=)
Date ranges are ?filter[ran_at_start]=…&filter[ran_at_end]=…, ISO 8601 date or datetime

Filters AND together: filter[topic_ids] + filter[provider_ids] narrows to prompts that match both.

Common filters

Filter	What it does
`filter[ran_at_start]` / `filter[ran_at_end]`	The window the metrics cover. Defaults to the last 30 days on metric and citation endpoints, 90 days on ads.
`filter[granularity]`	Bucket size of the time series (`day` by default) on the metric and share endpoints.
`filter[target_brand]`	Which brand name counts as “yours” for target metrics. Defaults to the brand’s own name.
`filter[brand_ids]`	Found-brand mapping ids — narrows which competitor rows count toward the metric.
`filter[provider_ids]` / `filter[region_ids]`	Scope to specific AI providers or regions.
`filter[topic_ids]`	Scope to prompts under these topics. Available on the prompt, citation and topic endpoints.
`filter[prompt_ids]`	Restrict a prompt list to specific prompts.
`filter[prompt_regions]`	`"promptId,regionId"` pairs, for when a prompt is tracked in several regions.
`filter[is_deleted]`	Include soft-deleted rows. Defaults to `false`.
`filter[types]`	Opportunity kind: `context_hint` (anchored on a tracked prompt), `keyword` (from a synced Google Ads account). Through the MCP server this is pinned to `context_hint`.
`filter[intents]`	Opportunity intent: `C` commercial, `I` informational, `T` transactional, `N` navigational.
`filter[list_ids]`	Restrict opportunities to members of these strategy lists.

Time windows

Metric endpoints return an aggregate_metrics block for the whole window plus time_based_metrics, one entry per bucket. diff on each row compares against the previous equal-length period — request 7 days and you’re comparing to the 7 days before that.

curl "https://core.cognizo.ai/api/v2/brands/BRAND_ID/share_of_voice?\
filter[ran_at_start]=2026-07-01&filter[ran_at_end]=2026-07-31&filter[granularity]=week" \
  -H "X-API-KEY: YOUR_API_KEY"

See Metrics & units for what the numbers mean.

Get started

Guides

Sorting

Filtering

Common filters

Time windows

​Pagination

​Sorting

​Filtering

​Common filters

​Time windows

Pagination

Sorting

Filtering

Common filters

Time windows