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

# Choose filters, groups, and subjects

> Use filters to select the answers you want to examine, groups to split the result, and a subject to choose the brands or sources returned.

Use filters to select the answers you want to examine, groups to split the result, and a subject to choose the brands or sources returned.

## Discover the available dimensions

Call `list_dimension_options` for the project. It returns options for `platform`, `topic`, `prompt_type`, `intent`, and `user_profile`, based on the latest run. An empty options list does not create a usable dimension. For an older run, confirm that the requested values exist in that run and inspect filter warnings.

Use returned labels exactly. A topic filter matches the named topic; “running shoes” should not be assumed to select “trail running shoes.” In the product, `prompt_type` corresponds to the **Category** facet and `intent` to **Customer Intent**.

```json theme={null}
{
  "filters": [
    {"dimension":"platform","values":["ChatGPT Search"]},
    {"dimension":"topic","values":["Tinted Mineral Face SPF"]}
  ],
  "group_by": ["platform","topic"]
}
```

This is an argument fragment for tools that accept these fields. Replace the example values with your project's options. Read `data.filters_applied` and its `warnings` before presenting the result; do not assume the requested filter was applied merely because the call succeeded.

Some grouped responses identify platforms with codes. The worked example returned `OPENAI` for ChatGPT Search and `VERTEX` for Gemini. Preserve the returned code and its known display label in an export. Do not invent labels for an unknown code.

Grouping support depends on the operation. Citation-score URL results do not apply `group_by` in this edition. Grounding-source platform grouping is available on the all-brand, unrestricted-sentiment path; narrower brand or sentiment requests can drop it. Check the operation’s parameter table and returned scope rather than assuming a dimension works on every tool.

## Choose the subject for citation tools

| `subject.kind` | What to request |
| - | - |
| `leaderboard` | Top rows; use `top_n` and inspect the returned count. |
| `all` | All available rows in the selected scope. |
| `owned` | The project's owned sources. |
| `specified` | Exact sources listed in `domains`. |

```json theme={null}
{"kind":"specified","domains":["colorescience.com"]}
```

## Choose the subject for brand tools

Brand measurement tools use `leaderboard`, `all`, `self`, `self_and_competitors`, or `specified`. For `specified`, provide `entities_or_bundles`:

```json theme={null}
{"kind":"specified","entities_or_bundles":["Colorescience"]}
```

Optional selection flags include `always_include_self`, `always_include_competitors`, and `include_non_brands` where supported. Citation selection uses `always_include_owned`. Do not swap these two subject formats.

## Check what was actually returned

Most measurement leaderboards default to 25 rows, with additional configured or owned rows where applicable. Inspect `subject_summary.n_returned` and `n_available`. Their difference can reflect your deliberate selection as well as truncation. These counts can include rows across groups, so do not label them “unique brands” without checking the grouping.

`unindexed_entities` means the requested name was not measured in the run's entity set. It does not prove the name never appeared in the answer text. `unscored_entities` means a requested entity lacks the sentiment result being requested.

Read `served_aggregation_level` or `requested_aggregation_level` when returned. Mention coverage requested at bundle level can be served at entity level; adding alias coverage values would double-count responses.

Sentiment also returns entity-level rows when `bundle` is requested in this edition. The grounding-source HTTP route does not apply `subject`; use its supported `brand_subset` selection.

Next: [Response fields and units](/developers/guides/09-responses-and-metrics).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.