--- title: fanout-queries description: Retrieve observed search and shopping queries. canonical_url: https://orchestor.io/docs/en/cli/fanout-query markdown_url: https://orchestor.io/docs/en/cli/fanout-query.md contentType: reference --- # fanout-queries `orc fanout-queries list` retrieves stored search and shopping query occurrences from API-provider responses and browser observations in a Workspace. Filter by prompt, observation slice, model, brand, and date range to inspect query expansion within particular observations. Authentication and access to the target Workspace are required. This does not run a new search or return aggregate metrics. Use query-fanout reports for aggregates. The same query text can occur repeatedly across observations or executions. ## Usage ```bash title="terminal" orc fanout-queries list --workspace ``` *Retrieve stored query occurrences.* ## Subcommands ### `list` Combine `--type search` or `shopping`, `--prompt-id`, `--observation-slice-id`, `--model-id`, and `--brand-id`. An observation slice ID restricts terms to one browser observation. Results are ordered by `generated_at` then ID descending; preserve filters when following cursors. ```bash title="terminal" orc fanout-queries list [options] ``` #### Unique options ##### `--type` Exact query kind. search selects search-style terms; shopping selects shopping terms. Omit to include both kinds.; enum: search|shopping Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --type ``` ##### `--prompt-id` Exact source prompt ID. Omit to include all prompts and rows without a prompt reference. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --prompt-id ``` ##### `--observation-slice-id` Exact browser observation slice ID. Excludes API-provider rows, which have no slice reference. Omit to include both provenance paths. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --observation-slice-id ``` ##### `--model-id` Exact stored model identifier. Browser observations use the model channel in this field; use a value returned by this endpoint. Omit to include all models. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --model-id ``` ##### `--brand-id` Exact stored brand ID. Browser-observation rows have no brand reference and are excluded when this filter is set. Omit to include all brands and unassigned rows. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --brand-id ``` ##### `--start-date` Inclusive timestamp lower bound supplied as a date (`YYYY-MM-DD`), starting at midnight. Omit for no lower bound. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --start-date ``` ##### `--end-date` Inclusive timestamp upper bound supplied as a date (`YYYY-MM-DD`). The current query compares generated_at to midnight at the start of this date, not the end of the day. Omit for no upper bound. Type: `string`. Optional. ```bash title="terminal" orc fanout-queries list --end-date ``` ## Examples ### Inspect shopping query expansion for a question ```bash title="terminal" orc fanout-queries list --prompt-id --type shopping --workspace --json ``` *Inspect shopping query expansion for a question* ### Retrieve a UTC date range Start and end are UTC calendar dates in `YYYY-MM-DD` format, inclusive at both ends. ```bash title="terminal" orc fanout-queries list --start-date 2026-10-01 --end-date 2026-10-03 --workspace ``` *Retrieve a UTC date range* ## Filters and empty results Filters are combined with AND; omitted filters do not restrict results. Follow `next_cursor` with the same filters. A nonempty page reports state `observed`. On an empty page, `fanout_availability` describes Workspace-wide collection evidence and lifecycle without these filters. It is not a count or proof that no search occurred. ## Aggregate query fanouts The Alpha `POST /v1/reports/fanout-aggregates` operation aggregates stored search query occurrences from API answers and completed browser observation slices. It uses actual fanout evidence. The existing query-fanouts report retains its legacy citation-based metric. Shopping queries are outside this report. Use `group_by: "query"` (default) to group after trimming, lowercasing and collapsing whitespace. `variations` lists up to 100 distinct original query strings, with `variation_count` and `variations_has_more` describing the full set. `share` is the group's occurrence count divided by all grouped occurrences. `execution_count` counts distinct linked executions; `per_execution_rate` divides this by `eligible_execution_count`, including confirmed empty captures. Unavailable captures are excluded. Rows with an unlinked historical occurrence return a null rate. API and browser copies linked to the same slice are counted once per original query. Use `group_by: "term_ngram"` with `ngram_size` from 1 through 5 (default 1) for contiguous terms split at non-alphanumeric characters. Repeated n-grams within one query count as repeated occurrences; execution counts remain distinct. N-gram shares use the total number of n-gram occurrences. Supply inclusive UTC `start_date`/`end_date`; optional `prompt_ids` and `model_ids` restrict both occurrences and the execution denominator. An empty filter array selects no executions. Unknown fields/groupings and `ngram_size` with query grouping return 400. `limit` and `offset` page the count-ranked results after shares are calculated. ```bash orc reports fanout-aggregates --start-date 2026-11-01 --end-date 2026-11-02 --group-by term_ngram --ngram-size 2 ``` MCP: `get_fanout_aggregate_report` accepts the same JSON fields. ## Global Options The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc fanout-queries`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--limit`](https://orchestor.io/docs/cli/global-flags.md) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) - [`--readonly`](https://orchestor.io/docs/cli/global-flags.md#read-only-mode) - [`--wrap-untrusted`](https://orchestor.io/docs/cli/global-flags.md#untrusted-content-wrapping) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)