​

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.

Retrieve stored query occurrences.

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.

Exact query kind. search selects search-style terms; shopping selects shopping terms. Omit to include both kinds.; enum: search|shopping

Type: string. Optional.

Exact source prompt ID. Omit to include all prompts and rows without a prompt reference.

Type: string. Optional.

Exact browser observation slice ID. Excludes API-provider rows, which have no slice reference. Omit to include both provenance paths.

Type: string. Optional.

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.

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.

Inclusive timestamp lower bound supplied as a date (YYYY-MM-DD), starting at midnight. Omit for no lower bound.

Type: string. Optional.

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.

Inspect shopping query expansion for a question

Start and end are UTC calendar dates in YYYY-MM-DD format, inclusive at both ends.

Retrieve a UTC date range

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.

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.

MCP: get_fanout_aggregate_report accepts the same JSON fields.

The following global options can be used with orc fanout-queries:

For details and examples, see global options.