​

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. Supported metrics and aggregation options differ by endpoint; do not reuse another report metric without checking applicability.

Retrieve a visibility report.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

Aggregate sentiment score and mention count.

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

Aggregate search fanout count and citation count from existing answers.

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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.

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.

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

Type: string. Required.

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

Type: string. Optional.

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

Type: string. Optional.

Comma-separated platform identifiers.

Type: string. Optional.

Comma-separated workspace topic identifiers.

Type: string. Optional.

Comma-separated prompt country codes.

Type: string. Optional.

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

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

Type: string. Optional.

(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.

(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.

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.

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.

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.

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.

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.

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.

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.

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

Type: string. Optional.

(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.

(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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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

Type: string. Optional.

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.

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.

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.

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.

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.

Prepare an interval and metric body.

Submit a body and receive JSON.

Retrieve citations co-occurring with an attribute.

Retrieve crawler counts for a registered domain.

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.

Retrieve shopping visibility from an existing body.

Retrieve shopping visibility trends.

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.

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.

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

The following global options can be used with orc reports:

For details and examples, see global options.