---
title: reports
description: Aggregate stored measurement metrics, evidence, and traffic.
canonical_url: https://orchestor.io/docs/en/cli/reports
markdown_url: https://orchestor.io/docs/en/cli/reports.md
contentType: reference
---

# reports

`orc reports` aggregates visibility, sentiment, citations, search, perception, and shopping metrics from stored Workspace observations. Select metrics, grouping axes, filters, and UTC intervals through a JSON body or flags. It also retrieves registered-domain crawler/referral traffic and citation evidence for perception attributes.

Retrieving reports does not start new measurements. For a short combined digest, use [`orc report`](https://orchestor.io/docs/en/cli/report.md). Supported metrics and aggregation options differ by endpoint; do not reuse another report metric without checking applicability.

## Usage

```bash title="terminal"
orc reports visibility get --workspace <workspace-id>
```

*Retrieve a visibility report.*

## Body and aggregation options

`scope` is brand, topic, prompt, or project. Non-project scopes require a scope ID; project does not filter by that ID. Preserve each response row own scope rather than inferring it only from the request selector. Omitted or empty dimensions and metrics use endpoint defaults. group_by adds axes with duplicates removed. persona_id is execution identity; the zero UUID means no persona. Exactly brand-only grouping on visibility/sentiment uses normalized comparison-brand mentions rather than prompt-owning brands.

Flat filters combine fields with AND and array values with any-match. Empty arrays add no condition. where and filters combine with AND. where accepts one condition or and/or groups nested up to five levels, with 1–100 expressions per group. Unknown flat keys may be ignored; use supported keys. order_by takes up to 20 keys applied in order; each field must be among requested axes or metrics. Omission sorts by the first grouping axis descending.

`include_examples` is accepted as a compatibility field but discarded by current handlers; true does not return `evidence_examples`.

## Subcommands

### `visibility get`

Aggregate visibility, mentions, share of voice, and average position.

```bash title="terminal"
orc reports visibility get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports visibility get --include-examples <value>
```

### `citations get`

Aggregate citation count and rate. Default axes are date and source_domain.

```bash title="terminal"
orc reports citations get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports citations get --include-examples <value>
```

### `sentiment get`

Aggregate sentiment score and mention count.

```bash title="terminal"
orc reports sentiment get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports sentiment get --include-examples <value>
```

### `query-fanouts get`

Aggregate search fanout count and citation count from existing answers.

```bash title="terminal"
orc reports query-fanouts get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports query-fanouts get --include-examples <value>
```

### `web-search-results get`

Aggregate search share and web result counts. Default axes are date and result_hostname.

```bash title="terminal"
orc reports web-search-results get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports web-search-results get --include-examples <value>
```

### `perception get`

Aggregate attribute mentions and answer counts from observed answers. Default axes are attribute and brand.

```bash title="terminal"
orc reports perception get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception get --include-examples <value>
```

### `perception-rankings get`

Retrieve perception attribute rankings. Grouping and metric are fixed: attribute_mention_count, ordered by attribute label.

```bash title="terminal"
orc reports perception-rankings get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception-rankings get --include-examples <value>
```

### `perception sources list`

Supply brand ID and attribute to retrieve citation URLs observed in the same AI answers. This is answer-level co-occurrence evidence, not proof that a URL caused the attribute. Active renamed definitions resolve to the original source label; hidden definitions return no evidence.

```bash title="terminal"
orc reports perception sources list [options]
```

#### Unique options

##### `--attribute`

Attribute label or stable source label. An active renamed definition is resolved to its historical source label. A hidden definition yields no evidence.; max 200 chars

Type: `string`. Required.

```bash title="terminal"
orc reports perception sources list --attribute <value>
```

##### `--brand-id`

Brand identifier in the selected workspace. Required; an unavailable brand returns 404.

Type: `string`. Required.

```bash title="terminal"
orc reports perception sources list --brand-id <value>
```

##### `--start-date`

Inclusive UTC calendar date (YYYY-MM-DD). Omit for no lower bound.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception sources list --start-date <value>
```

##### `--end-date`

Inclusive UTC calendar date (YYYY-MM-DD). Omit for no upper bound. Must not precede start_date.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception sources list --end-date <value>
```

##### `--filter[platform]`

Comma-separated platform identifiers.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception sources list --filter[platform] <value>
```

##### `--filter[topic-id]`

Comma-separated workspace topic identifiers.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception sources list --filter[topic-id] <value>
```

##### `--filter[country-code]`

Comma-separated prompt country codes.

Type: `string`. Optional.

```bash title="terminal"
orc reports perception sources list --filter[country-code] <value>
```

### `bots get`

Retrieve AI crawler traffic for a registered Workspace-owned domain. The metric is count. Domain normalization lowercases and removes HTTP(S) prefix, [www](http://www/)., and path; missing active registration returns 403.

```bash title="terminal"
orc reports bots get [options]
```

#### Unique options

##### `--domain`

(required) Registered domain owned by the authenticated workspace. The server lowercases it and removes an HTTP(S) prefix, [www](http://www/). prefix and path. Returns 403 if no active domain registration belongs to the workspace.

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --domain <value>
```

##### `--metrics`

(required) Required metrics. Bots supports count. Referrals supports legacy visits; requesting utm_visits, referred_visits, human_visits or ai_traffic_share enables human page-request aggregation.; csv

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --metrics <value>
```

##### `--start-date`

(required) Inclusive lower calendar-date bound. Use YYYY-MM-DD. The query casts this value to a database date; time-of-day does not provide hourly filtering.

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --start-date <value>
```

##### `--end-date`

Inclusive upper calendar-date bound. Use YYYY-MM-DD. Defaults to the current database date when omitted. A time component does not make this an exclusive timestamp bound.

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --end-date <value>
```

##### `--granularity`

Human referral aggregation supports day, week and month; other intervals are rejected. Legacy reports read daily aggregates.; enum: hour|day|week|month|quarter|year|relative_week

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --granularity <value>
```

##### `--dimensions`

Human referral rows group by date and ai_source, optionally landing_path. Other dimensions are rejected. Legacy bots uses date and crawler.; csv

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --dimensions <value>
```

##### `--filters`

Accepted but not applied by the current bots or referrals handler. Omission has the same effect as supplying filters; do not rely on this field to restrict report rows.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --filters <value>
```

##### `--order-by`

Accepted but not applied. Rows are always ordered by date descending, then crawler (bots) or ai_source (referrals) ascending.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --order-by <value>
```

##### `--pagination`

Row limit settings. The current handlers apply limit only; offset is ignored. has_more is always false and totals cover only returned rows, so they do not prove that the full date range fits within the limit.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports bots get --pagination <value>
```

### `referrals get`

Retrieve AI assistant referral traffic. Legacy metric is visits. Requesting utm_visits, referred_visits, human_visits, or ai_traffic_share enables human page-request aggregation.

```bash title="terminal"
orc reports referrals get [options]
```

#### Unique options

##### `--domain`

(required) Registered domain owned by the authenticated workspace. The server lowercases it and removes an HTTP(S) prefix, [www](http://www/). prefix and path. Returns 403 if no active domain registration belongs to the workspace.

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --domain <value>
```

##### `--metrics`

(required) Required metrics. Bots supports count. Referrals supports legacy visits; requesting utm_visits, referred_visits, human_visits or ai_traffic_share enables human page-request aggregation.; csv

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --metrics <value>
```

##### `--start-date`

(required) Inclusive lower calendar-date bound. Use YYYY-MM-DD. The query casts this value to a database date; time-of-day does not provide hourly filtering.

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --start-date <value>
```

##### `--end-date`

Inclusive upper calendar-date bound. Use YYYY-MM-DD. Defaults to the current database date when omitted. A time component does not make this an exclusive timestamp bound.

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --end-date <value>
```

##### `--granularity`

Human referral aggregation supports day, week and month; other intervals are rejected. Legacy reports read daily aggregates.; enum: hour|day|week|month|quarter|year|relative_week

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --granularity <value>
```

##### `--dimensions`

Human referral rows group by date and ai_source, optionally landing_path. Other dimensions are rejected. Legacy bots uses date and crawler.; csv

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --dimensions <value>
```

##### `--filters`

Accepted but not applied by the current bots or referrals handler. Omission has the same effect as supplying filters; do not rely on this field to restrict report rows.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --filters <value>
```

##### `--order-by`

Accepted but not applied. Rows are always ordered by date descending, then crawler (bots) or ai_source (referrals) ascending.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --order-by <value>
```

##### `--pagination`

Row limit settings. The current handlers apply limit only; offset is ignored. has_more is always false and totals cover only returned rows, so they do not prove that the full date range fits within the limit.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports referrals get --pagination <value>
```

### `shopping-performance get`

Retrieve product visibility and appearances from existing shopping observations. Does not start a measurement. Uses a ShoppingReportOptions body; filters.product_id is a product ID in the selected Workspace.

```bash title="terminal"
orc reports shopping-performance get [options]
```

### `shopping-demand get`

Retrieve search demand from existing shopping fanout queries. Does not start a measurement; uses a ReportOptions body and shared body-first flags.

```bash title="terminal"
orc reports shopping-demand get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports shopping-demand get --include-examples <value>
```

### `shopping-trend get`

Retrieve product visibility trends from existing shopping observations. Does not start a measurement; select a target with filters.product_id in the ShoppingReportOptions body.

```bash title="terminal"
orc reports shopping-trend get [options]
```

### `merchants get`

Retrieve appearance counts by merchant from existing shopping observations. Does not start a measurement.

```bash title="terminal"
orc reports merchants get [options]
```

#### Unique options

##### `--scope`

Select the aggregation scope. project means the active workspace, not a project ID. Defaults to project. brand, topic and prompt require scope_id.; enum: brand|topic|prompt|project

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --scope <value>
```

##### `--scope-id`

Identifier selected by scope: brand ID, topic ID or prompt ID. Required for non-project scopes. Omit for project; project scope does not filter by this value.

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --scope-id <value>
```

##### `--dimensions`

Grouping axes. Omit or send [] to use endpoint defaults: [date] for visibility, sentiment and query-fanouts; [date, source_domain] for citations; [date, result_hostname] for web-search-results; [attribute, brand] for perception. perception-rankings fixes its own grouping. persona_id refers to execution identity; the zero UUID means no execution persona. Exactly [brand] on visibility or sentiment uses normalized comparison-brand mentions.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --dimensions <value>
```

##### `--metrics`

Requested metrics. Omit or send [] for endpoint defaults. Use visibility_rate, mention_count, share_of_voice or average_position for visibility; citation_count or citation_rate for citations; sentiment_score or mention_count for sentiment; fanout_count or citation_count for query-fanouts; search_share or web_search_result_count for web-search-results; attribute_mention_count or answer_count for perception. perception-rankings fixes attribute_mention_count. Shopping reports use rendered_visibility, appearances, average_position and win_rate. Unsupported combinations are not guaranteed meaningful values.; csv of: visibility_rate|mention_count|citation_count|citation_rate|sentiment_score|fanout_count|share_of_voice|average_position|web_search_result_count|search_share|attribute_mention_count|answer_count|rendered_visibility|appearances|win_rate

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --metrics <value>
```

##### `--filters`

Simple equality filters. Values can be strings, string arrays, numbers or booleans. Array values match any supplied item; empty arrays add no condition. Different fields combine with AND, and the result combines with where using AND. Supported common keys include platform, model, brand_id, topic_id, prompt_id, country_code, persona, persona_id, sentiment, brand_mentioned and source_domain. Web-search results additionally support search_query, result_url, result_hostname and result_rank. Unknown flat keys can be ignored; use documented keys.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --filters <value>
```

##### `--where`

One condition, an and group, or an or group. Groups can nest to five levels; each group contains 1–100 expressions.

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --where <value>
```

##### `--order-by`

Up to 20 sort keys, applied in array order. Each field must be requested in dimensions, group_by or metrics. Omit or send [] to sort by the first grouping axis descending. Perception ranking rows are always ordered by attribute label.; JSON array of objects (use --stdin for large resources)

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --order-by <value>
```

##### `--date-range`

Supply both start and end for a fixed UTC [start, end) interval, or period for a window ending now. Both explicit bounds take precedence over period. If only one bound accompanies period, the period window is used. Omit the whole object for the last 30 days; an empty object is invalid.; (JSON object, e.g. '{"custom_id":"x"}')

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --date-range <value>
```

##### `--granularity`

Time bucket for the date grouping axis. Defaults to day; accepted values are hour, day, week and month.; enum: hour|day|week|month

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --granularity <value>
```

##### `--group-by`

Additional grouping axes appended to dimensions, with duplicates removed. Omit for no additional axes.; csv of: date|platform|model|brand|product|topic|prompt|competitor|source_domain|source_page|search_query|result_url|result_hostname|result_rank|adopted|persona|persona_id|attribute|merchant

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --group-by <value>
```

##### `--include-examples`

Reserved compatibility field. The current report handlers discard this field and do not return evidence_examples; setting true does not enable evidence output.

Type: `string`. Optional.

```bash title="terminal"
orc reports merchants get --include-examples <value>
```

## Examples

### Prepare an interval and metric body.

```json title="visibility-report.json"
{
  "scope": "project",
  "dimensions": [
    "date"
  ],
  "metrics": [
    "visibility_rate"
  ],
  "date_range": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z"
  },
  "granularity": "day"
}
```

*Prepare an interval and metric body.*

### Submit a body and receive JSON.

```bash title="terminal"
orc reports visibility get --stdin < visibility-report.json --json
```

*Submit a body and receive JSON.*

### Retrieve citations co-occurring with an attribute.

```bash title="terminal"
orc reports perception sources list --brand-id <brand-id> --attribute "Customer support" --page-all
```

*Retrieve citations co-occurring with an attribute.*

### Retrieve crawler counts for a registered domain.

```bash title="terminal"
orc reports bots get --domain example.com --metrics count --start-date 2026-09-01 --end-date 2026-09-30 --json
```

*Retrieve crawler counts for a registered domain.*

### Retrieve shopping visibility from an existing body.

Prepare ShoppingReportOptions using the selected Workspace product IDs. Omitted or empty dimensions/metrics use endpoint defaults. Filters pass to API schema validation without client reinterpretation.

```bash title="terminal"
orc reports shopping-performance get --workspace <workspace-id> --stdin --json < shopping-report.json
```

*Retrieve shopping visibility from an existing body.*

### Retrieve shopping visibility trends.

```bash title="terminal"
orc reports shopping-trend get --workspace <workspace-id> --stdin --json < shopping-report.json
```

*Retrieve shopping visibility trends.*

## Intervals and evidence retrieval

Body-first report date_range uses both start/end for a UTC half-open `[start, end)` interval, or period for a window ending now. Both explicit bounds take precedence over period; one bound with period uses the period window. Omission uses the last 30 days; an empty object is invalid. Granularity accepts hour, day, week, or month, defaulting to day.

Perception source bounds are inclusive UTC calendar dates, with end not before start. Filter by platform, topic, or country and pass cursors unchanged. `--page-all` streams every page as NDJSON.

## Traffic report constraints

Bots/referrals use inclusive start/end calendar dates; omitted end uses the current database date. Adding time components does not provide hourly filtering or an exclusive upper bound. Legacy bots group by date/crawler; human referrals group by date/ai_source with optional landing_path, using day/week/month grains.

Traffic handlers do not apply filters or order_by. Ordering is date descending, then crawler/ai_source ascending. Pagination applies limit only and ignores offset. has_more is always false and totals cover returned rows only, so they do not prove the full interval was read.

## Permissions

Authenticate and select the target Workspace. Access to that Workspace is required.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc reports`:

- [`--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)