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

# Reports API: Queries

> The queries entity - the web searches AI platforms ran while answering your prompts.

`POST /api/v1/projects/{project}/reports/queries`

When a platform searches the web before it answers, it runs one or more searches first. These are its fan-out queries: the searches whose top results the AI read, so content that ranks for them is what shapes the answer. The answer panel lists them one answer at a time (see [Brand Mentions](/docs/brand-mentions)); this entity counts them across every answer in scope.

One row per search, or per platform, country, topic, tag, prompt or time bucket, or any mix of those. Read the [Reports API](/docs/reports-api) page first for the request shape, filter roles and the compare window.

> [!NOTE]
>
> Only searches the platform ran are counted. Some platforms, Perplexity among them, also suggest follow-up questions under an answer; those were never searched, so they never appear here. Platforms that answer from their own knowledge run no searches: their answers count in `answers` and lower `search_rate`.

## Dimensions

| id | Row | Label columns |
| - | - | - |
| `query` | One row per search text. Searches that differ only in letter case are one row, shown with one of their spellings. Only searches that ran in the window appear. | `query` |
| `service`, `country`, `tag`, `topic`, `prompt`, `date`, `week`, `month` | As on visibility. Without `query`, every group with answers has a row, zero when its answers ran no search. | `prompt` adds `prompt_uuid`, `topic` adds `topic_uuid`, `tag` adds `tag_uuid` |

## Measures

| id | Meaning | Unit |
| - | - | - |
| `runs` | Searches run in the group. An answer runs each of its searches once. | count |
| `answers` | Every answer in the row's population group, with or without searches: the denominator | count |
| `answers_with_searches` | Answers in the group that ran at least one search | count |
| `search_rate` | `answers_with_searches` ÷ `answers` | decimal, `percent` |
| `searches_per_answer` | `runs` ÷ `answers_with_searches`: how many searches an answer ran when it searched at all. Null when none did. | 2 decimals |
| `distinct_queries` | Different search texts in the group, ignoring case | count |
| `prompts` | Prompts whose answers ran the row's searches | count |
| `share` | The row's `runs` ÷ all runs in its population group. Shares in one group sum to 1. | decimal, `percent` |
| `rank` | Position by `runs` within the group, then the search text. Without `query`, the rows rank against each other. Assigned before row filters. | integer |

With `query` on the row, `answers` is the same for every search in a group, so `runs ÷ answers` is how often that search came up per answer.

## Filters

* Population fields as on the main page: `service`, `country`, `tag`, `topic`, `prompt`, `mentions_brand`, `cites_domain`, `mention_sentiment`, `carries_narrative`, `carries_theme`. They change every number, `answers` included.
* `query` is an entity field and needs `query` in `dimensions`. `in` and `not_in` match the text in any letter case; `contains` searches it: `{ "field": "query", "op": "contains", "value": "pricing" }`.
* Measures take comparisons: `{ "field": "runs", "op": "gte", "value": 5 }`.

There is no value list for `query`: search texts are near-unique. Page through them with `limit` and `offset` as you would URLs on [sources](/docs/reports-api-sources); `rank` stays correct on every page.

## Related blocks

| id | Per row |
| - | - |
| `prompts_for_query` | Up to ten prompts whose answers ran the row's search, in the row's group, most runs first: `{ "uuid", "prompt", "runs" }`. Needs `query` on the row. |

## Examples

### Headline numbers

How often the answers searched, how many searches they ran, and how varied those were, against the previous period. `benchmarks[0]` carries the trend of the first measure.

```json theme={null}
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": [],
  "measures": ["runs", "answers", "answers_with_searches", "search_rate", "searches_per_answer", "distinct_queries"]
}
```

### Searches per prompt

One row per prompt answered in the window, zero-filled, with the previous period for the change. Sort by `runs_change` for the prompts whose answers search more than they did.

```json theme={null}
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": ["prompt"],
  "measures": ["answers", "answers_with_searches", "runs", "distinct_queries", "searches_per_answer"],
  "order_by": [{ "field": "runs", "dir": "desc" }]
}
```

### Top searches

The searches run most, with how many prompts led to each, their share of all searches, and the prompts behind them.

```json theme={null}
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": ["query"],
  "measures": ["runs", "prompts", "share", "rank"],
  "related": ["prompts_for_query"],
  "limit": 25
}
```

Add `{ "field": "query", "op": "contains", "value": "pricing" }` to `filters` for a search box. Add `service` to `dimensions` to see each search per platform, with `share` then a share of that platform's searches.

### Searches per platform over time

Runs per platform per day, for a chart. `searches_per_answer` shows whether a platform is searching harder, not just answering more.

```json theme={null}
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["service", "date"],
  "measures": ["runs", "answers", "searches_per_answer", "search_rate"],
  "order_by": [{ "field": "date", "dir": "asc" }],
  "limit": 1000
}
```

For one search over time, add `query` to `dimensions` and filter it: `{ "field": "query", "op": "in", "values": ["best crm software"] }`.

### The prompts behind a search

One row per prompt whose answers ran the search, with the platforms split out. `prompts_for_query` gives the same list in a block when you are already listing searches.

```json theme={null}
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": ["prompt", "query", "service"],
  "measures": ["runs"],
  "filters": [{ "field": "query", "op": "in", "values": ["best crm software"] }],
  "order_by": [{ "field": "runs", "dir": "desc" }]
}
```


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