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

# Filters and time ranges

> Shared query parameters and the values each one accepts.

Most read endpoints share a small set of query parameters. Learn these four — `range`, `region`, `engines` and `brand_slug` — and the rest of the API follows the same shape.

## Value scales

<Note>
  Two fields express visibility on different scales. `citation_rate` on `/brands/{slug}/snapshots` is a fraction from `0` to `1`, and so is the `per_engine` map beside it. `score` on `/model` runs from `0` to `100`. Multiply the snapshot values by 100 when you chart the two together.
</Note>

Treat the scale as part of the endpoint contract. [Visibility Score](/metrics/visibility-score) explains what the number itself means.

## `range` — the time window

Send one of these four and you'll get identical behaviour everywhere:

`7d` · `30d` · `90d` · `365d`

Leave it off and you get 30 days. Some endpoints accept extra aliases beyond the four:

| Endpoints                                                         | Also accepts                                           |
| ----------------------------------------------------------------- | ------------------------------------------------------ |
| Brands, snapshots, portfolio, citations, fan-outs, industry       | `1w`/`week`, `1m`/`month`, `3m`/`quarter`, `1y`/`year` |
| `/brands/{slug}/agents`, `/brands/{slug}/agents/pages`            | Nothing                                                |
| `/brands/{slug}/attribution`, `/brands/{slug}/search-performance` | Nothing                                                |

Stick to `7d`, `30d`, `90d` or `365d` and every endpoint answers the same way. `/brands/{slug}/attribution` and `/brands/{slug}/search-performance` reject anything outside that set with `400 range must be one of 7d/30d/90d/365d`.

Windows are computed in UTC. The brand, portfolio and industry endpoints use whole days ending today, inclusive. The citation endpoints use a rolling window from exactly N × 24 hours ago, so counts can differ slightly from a whole-day view of the same period.

`/model` takes no `range` at all. It's always the last 30 days, and it echoes `"range": "30d"` back so you can see that.

## `engines` — filtering by AI engine

Nine engine slugs exist. Send them exactly as written:

| Engine       | Slug           |
| ------------ | -------------- |
| ChatGPT      | `chatgpt`      |
| Claude       | `claude`       |
| Gemini       | `gemini`       |
| Perplexity   | `perplexity`   |
| Copilot      | `copilot`      |
| DeepSeek     | `deepseek`     |
| Grok         | `grok`         |
| AI Overviews | `ai_overviews` |
| AI Mode      | `ai_mode`      |

Matching is exact against the stored value, so use the slug rather than a vendor name like `openai` or a display name like `AI Overviews`.

Where each one goes:

* `/citations` takes `engines` as a comma-separated list — `engines=chatgpt,perplexity`.
* `/industry/ranking` takes `engines` (comma-separated) or the singular `engine`. The plural wins if you send both.
* `/industry/metrics` takes a single `engine` only.

<Note>
  You'll only have data for engines your plan actually scans. Lite and Growth scan six; `claude`, `grok` and `deepseek` are Enterprise. Filtering by an engine you don't scan returns an empty result, not an error. See [Plans and limits](/plans-and-limits).
</Note>

## `region` and `language`

`region` is a lowercase ISO 3166-1 alpha-2 country code — `us`, `gb`, `de`, `in`. `language` is a lowercase ISO 639-1 code — `en`, `de`, `es`.

They aren't wired up identically:

| Endpoint                  | Parameters                              | Default when omitted              |
| ------------------------- | --------------------------------------- | --------------------------------- |
| `/brands/{slug}/mentions` | `region`, `language`                    | The brand's primary active region |
| `/industry/metrics`       | `region`, `language`                    | The brand's primary active region |
| `/industry/gap`           | `region`                                | All regions                       |
| `/industry/ranking`       | `regions` (comma-separated), `language` | All regions                       |
| `/citations`              | `regions` (comma-separated)             | All regions                       |
| `/portfolio`              | `region`, `language`                    | `us` and `en`                     |

`/portfolio` defaults to `us` and `en` rather than to your brand's own region. If you track brands outside the US, send `region` and `language` explicitly — `region=de&language=de`, for example.

`/brands/{slug}/snapshots` takes no region parameter. It resolves the brand's primary active region for you, which is why its numbers line up with the dashboard.

## `brand_slug` — picking a brand

Account-wide endpoints don't carry a brand in the path. They default to your **newest** tracked brand, and accept `brand_slug` to choose another:

`/topics` · `/model` · `/citations` · `/industry/metrics` · `/industry/ranking` · `/industry/gap` · `/industry/competitors/{name}/citations` · `/industry/competitors/{name}/prompts`

<Note>
  Read your slugs from `GET /brands` rather than composing them by hand. A slug that matches nothing resolves to the default scope instead of raising an error, so a typo returns a valid-looking answer for the wrong brand.
</Note>

Slugs are lowercase and hyphenated, and `GET /brands` lists yours.

## Endpoint-specific filters

**`/brands/{slug}/mentions`** takes `sentiment`, one of `pos`, `neu` or `neg`. Anything else returns `400 invalid sentiment filter`. The endpoint returns up to 100 mentions per call, so narrow with `sentiment` and `region` to get the set you want.

**`/industry/ranking`** needs at least one of `topics`, `engines` or `regions`. Call it with only a `range` and you get `400 at least one of topics, engines, or regions is required`. Topics cap at 50 per request and 100 characters each.

**The agent endpoints** (`/brands/{slug}/agents` and `/agents/pages`) share three crawler filters, which combine with AND:

* `bot` — exact bot name, like `GPTBot`.
* `vendor` — exact operator, like `OpenAI`. Covers every bot that company runs.
* `kind` — one of `training_crawler`, `browsing_agent`, `agentic_browser`, `mcp_client`.

[Agent analytics](/agent-analytics) explains what those four kinds mean in practice.

**`/agents/pages`** adds list controls: `search` (substring on the path, truncated at 200 characters), `folder`, `limit` (default `10`), `offset`, `sort` (`hits`, `path`, `errors` or `uniques`) and `dir` (`asc` or `desc`). `dir` is only honoured when you also send `sort`.

`status` on that endpoint accepts `ok`, `error`, or a bare three-digit code like `404`.

## A worked example

Perplexity citations for one brand in the UK, last quarter:

```bash theme={null}
curl -G "https://api.fixaeo.com/api/public/v1/citations" \
  -H "Authorization: Bearer fixaeo_xxx" \
  -d "range=90d" \
  -d "brand_slug=acme" \
  -d "engines=perplexity" \
  -d "regions=gb"
```

## Related

<CardGroup cols={2}>
  <Card icon="code" title="Customer API" href="/api/introduction">
    Base URL, the 21 paths, and the error table.
  </Card>

  <Card icon="gauge-high" title="Rate limits" href="/api/rate-limits">
    Why a wider `range` beats a loop over days.
  </Card>

  <Card icon="key" title="Authentication" href="/api/authentication">
    Creating and rotating the key these calls need.
  </Card>

  <Card icon="wrench" title="MCP tools" href="/mcp/tools">
    The same filters, as arguments on 14 read-only tools.
  </Card>
</CardGroup>