> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognizo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination & filtering

> Page, sort, and filter list endpoints consistently.

Every list endpoint follows the same conventions.

## Pagination

Top-level `page` and `page_size` query params:

```bash theme={null}
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**; `list_brands` defaults to **50**. A
value above the cap is **clamped, not rejected**, so asking for 1,000 quietly
gives you the maximum. The `meta` block tells you where you actually are:

```json theme={null}
{
  "data": [ ],
  "meta": { "page": 2, "page_size": 50, "total_items": 240, "total_pages": 5 }
}
```

<Note>
  `page` + `page_size` is the only pagination contract — `limit`, `offset`,
  `skip`, and `per_page` are not accepted.
</Note>

## 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`                                                    |

## 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.

### Filters worth knowing

| 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`.                                                                      |

## 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.

```bash theme={null}
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](/guides/metrics) for what the numbers mean.