--- title: sources description: Inspect answer sources, citations, and competitor gaps. canonical_url: https://orchestor.io/docs/en/cli/source markdown_url: https://orchestor.io/docs/en/cli/source.md contentType: reference --- # sources `orc sources` inspects source domains, URLs, citation aggregates, and source gaps in Workspace answers involving competitors. Choose domain, host, or URL views, and narrow the answer population by dates, brand, topic, tags, and platform. It uses stored retrieval evidence and citations; it does not start a new measurement. `--project` is a compatibility query parameter, but current endpoints do not apply a project filter. Narrow the target with supported brand, topic, or prompt tag filters. ## Usage ```bash title="terminal" orc sources domains list ``` *List source domains.* ## Dates and cohorts Start and end are inclusive UTC calendar dates, `YYYY-MM-DD`. `top` includes sources with current retrievals or citations; `new` requires first retrieval within the interval; `trending` and `losing` reflect retrieval increases and decreases. Cohorts can overlap. Trending and losing require both dates and compare against the immediately preceding interval of the same day count. Missing either bound returns no rows. Domain list default sorting is citation_count without a cohort, retrieval_count for top, first_seen_at for new, and retrieval_change for trending/losing. Losing defaults to ascending order; others descend. Override with `--order`. ## Subcommands ### `gaps list` Use `--min-competitors` for the minimum number of distinct configured competitors in an answer. `--view` accepts domain, host, or url, defaulting to domain. `--mentioned-brand-operator or` / `and` selects any/all specified mentioned brands. Hostname, URL, and title search is case-insensitive. ```bash title="terminal" orc sources gaps list [options] ``` #### Unique options ##### `--view` Grouping axis: domain combines subdomains under their registrable domain; host keeps captured hostnames; url keeps individual citation URLs. Defaults to domain.; enum: domain|host|url Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --view ``` ##### `--min-competitors` Minimum distinct configured competitors found in an answer. Type: `number`. Optional. ```bash title="terminal" orc sources gaps list --min-competitors ``` ##### `--start-date` Inclusive UTC start date (YYYY-MM-DD). Omit for no lower bound. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --start-date ``` ##### `--end-date` Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --end-date ``` ##### `--search` Case-insensitive source hostname, URL, or title search. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --search ``` ##### `--filter[platform]` Comma-separated platform identifiers, such as openai or anthropic. Values are trimmed and lowercased. Matches any selected platform; omit or send an empty value for no platform filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[platform] ``` ##### `--filter[topic-id]` Comma-separated topic IDs for the answer population. Matches any selected topic in the workspace. Omit or send an empty value for no topic filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[topic-id] ``` ##### `--filter[brand-id]` Comma-separated IDs of the brands that own the answer prompts. Matches any selected parent brand in the workspace; this does not select every brand mentioned in an answer. Omit for no parent-brand filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[brand-id] ``` ##### `--filter[tag]` Comma-separated prompt tag names, not tag IDs. Values are trimmed and lowercased. Matches any selected name. Omit or send an empty value for no tag filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[tag] ``` ##### `--filter[mentioned-brand-id]` Comma-separated competitor Brand IDs that must be mentioned in qualifying answers. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[mentioned-brand-id] ``` ##### `--filter[country]` Comma-separated ISO 3166-1 alpha-2 country codes for qualifying prompts. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[country] ``` ##### `--mentioned-brand-operator` Whether any or all selected mentioned Brand IDs must occur in a qualifying answer.; enum: or|and Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --mentioned-brand-operator ``` ##### `--filter[domain-classification]` Comma-separated SourceDomainClassification values. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[domain-classification] ``` ##### `--filter[url-classification]` Comma-separated SourceUrlClassification values. Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --filter[url-classification] ``` ##### `--sort` Field used to order the derived gap rows.; enum: source|competitor_count|retrieval_count|retrieved_percentage|retrieval_rate|citation_rate|gap_score Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --sort ``` ##### `--order` Sort direction.; enum: asc|desc Type: `string`. Optional. ```bash title="terminal" orc sources gaps list --order ``` ##### `--page` One-based page number. Defaults to 1; values above 100000 are capped. Reuse the same filters when incrementing the page. Type: `number`. Optional. ```bash title="terminal" orc sources gaps list --page ``` ### `domains list` Domain view combines subdomains under registrable domains using the Public Suffix List; host view preserves normalized captured hostnames. Classification vocabulary differs between domain and host. `--page` is one-based, defaults to 1, and is capped above 100000. ```bash title="terminal" orc sources domains list [options] ``` #### Unique options ##### `--project` Compatibility query parameter; this endpoint does not apply a project filter. Use the supported brand, topic or prompt-tag filters to narrow the workspace data. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --project ``` ##### `--view` Grouping axis: domain combines subdomains under their registrable domain using the Public Suffix List; host keeps normalized captured hostnames. Defaults to domain.; enum: domain|host Type: `string`. Optional. ```bash title="terminal" orc sources domains list --view ``` ##### `--start-date` Inclusive UTC start date (YYYY-MM-DD). Omit for no lower bound. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --start-date ``` ##### `--end-date` Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --end-date ``` ##### `--cohort` Optional source subset: top includes any current retrieval or citation; new requires a retrieval and first retrieval within the selected period; trending and losing require a positive or negative retrieval change. Cohorts can overlap. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows.; enum: top|new|trending|losing Type: `string`. Optional. ```bash title="terminal" orc sources domains list --cohort ``` ##### `--filter[platform]` Comma-separated platform identifiers, such as openai or anthropic. Values are trimmed and lowercased. Matches any selected platform; omit or send an empty value for no platform filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --filter[platform] ``` ##### `--filter[topic-id]` Comma-separated topic IDs for the answer population. Matches any selected topic in the workspace. Omit or send an empty value for no topic filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --filter[topic-id] ``` ##### `--filter[brand-id]` Comma-separated IDs of the brands that own the answer prompts. Matches any selected parent brand in the workspace; this does not select every brand mentioned in an answer. Omit for no parent-brand filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --filter[brand-id] ``` ##### `--filter[tag]` Comma-separated prompt tag names, not tag IDs. Values are trimmed and lowercased. Matches any selected name. Omit or send an empty value for no tag filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --filter[tag] ``` ##### `--filter[classification]` Comma-separated classification values. Matches any supplied value; omit to include all classifications. In host view use host-role values; in domain view use domain classification values. Type: `string`. Optional. ```bash title="terminal" orc sources domains list --filter[classification] ``` ##### `--sort` Sort field. When omitted: citation_count without cohort; retrieval_count for top; first_seen_at for new; retrieval_change for trending or losing. retrieval_change requires cohort.; enum: hostname|classification|retrieval_count|retrieval_change|retrieval_rate|retrieval_frequency|citation_count|citation_rate|url_count|share_of_voice|first_seen_at|last_seen_at Type: `string`. Optional. ```bash title="terminal" orc sources domains list --sort ``` ##### `--order` Sort direction. When omitted, losing uses ascending order and all other cases use descending order. Set explicitly to override the cohort default.; enum: asc|desc Type: `string`. Optional. ```bash title="terminal" orc sources domains list --order ``` ##### `--page` One-based page number. Defaults to 1; values above 100000 are capped. Reuse the same filters when incrementing the page. Type: `number`. Optional. ```bash title="terminal" orc sources domains list --page ``` ### `domains get` Retrieve details using a source-domain hostname returned by the host-view list. Distinguish it from a domain rollup display value. ```bash title="terminal" orc sources domains get [options] ``` ### `urls list` List source URLs. Use returned cursors unchanged and retain dates and filters. Without a cohort, default sorting is by citation_count. Sorting by retrieval_count or retrieval_change requires a cohort. ```bash title="terminal" orc sources urls list [options] ``` #### Unique options ##### `--project` Compatibility query parameter; this endpoint does not apply a project filter. Use the supported brand, topic or prompt-tag filters to narrow the workspace data. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --project ``` ##### `--start-date` Inclusive UTC start date (YYYY-MM-DD). Omit for no lower bound. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --start-date ``` ##### `--end-date` Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --end-date ``` ##### `--cohort` Optional source subset: top includes any current retrieval or citation; new requires a retrieval and first retrieval within the selected period; trending and losing require a positive or negative retrieval change. Cohorts can overlap. For trending or losing, provide both start_date and end_date. The comparison period immediately precedes the selected period and has the same inclusive day count. Without both bounds these cohorts return no rows.; enum: top|new|trending|losing Type: `string`. Optional. ```bash title="terminal" orc sources urls list --cohort ``` ##### `--filter[platform]` Comma-separated platform identifiers, such as openai or anthropic. Values are trimmed and lowercased. Matches any selected platform; omit or send an empty value for no platform filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --filter[platform] ``` ##### `--filter[topic-id]` Comma-separated topic IDs for the answer population. Matches any selected topic in the workspace. Omit or send an empty value for no topic filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --filter[topic-id] ``` ##### `--filter[brand-id]` Comma-separated IDs of the brands that own the answer prompts. Matches any selected parent brand in the workspace; this does not select every brand mentioned in an answer. Omit for no parent-brand filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --filter[brand-id] ``` ##### `--filter[tag]` Comma-separated prompt tag names, not tag IDs. Values are trimmed and lowercased. Matches any selected name. Omit or send an empty value for no tag filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --filter[tag] ``` ##### `--filter[classification]` Comma-separated classification values. Matches any supplied value; omit to include all classifications. For citation aggregates, classification_scope selects the vocabulary. Type: `string`. Optional. ```bash title="terminal" orc sources urls list --filter[classification] ``` ##### `--sort` Sort field. When omitted: citation_count without cohort; retrieval_count for top; first_seen_at for new; retrieval_change for trending or losing. retrieval_count and retrieval_change require cohort.; enum: url|hostname|retrieval_count|retrieval_change|citation_count|share_of_voice|first_seen_at|last_seen_at Type: `string`. Optional. ```bash title="terminal" orc sources urls list --sort ``` ##### `--order` Sort direction. When omitted, losing uses ascending order and all other cases use descending order. Set explicitly to override the cohort default.; enum: asc|desc Type: `string`. Optional. ```bash title="terminal" orc sources urls list --order ``` ### `urls get` Retrieve details with the URL-encoded source URL returned by listing. It does not register a new source or request a URL crawl. ```bash title="terminal" orc sources urls get [options] ``` ### `citations list` Supply comma-separated domain, hostname, url, classification, or date values to `--group-by`; there is no default grouping. Including date requires `--bucket-width day`, `week`, or `month`. Classification scope selects domain, host, or url. ```bash title="terminal" orc sources citations list [options] ``` #### Unique options ##### `--project` Compatibility query parameter; this endpoint does not apply a project filter. Use the supported brand, topic or prompt-tag filters to narrow the workspace data. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --project ``` ##### `--start-date` Inclusive UTC start date (YYYY-MM-DD). Omit for no lower bound. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --start-date ``` ##### `--end-date` Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --end-date ``` ##### `--group-by` One or more grouping axes separated by commas: domain, hostname, url, classification or date. No default. Use bucket_width when date is included. Type: `string`. Required. ```bash title="terminal" orc sources citations list --group-by ``` ##### `--bucket-width` Calendar date bucket width. Required when group_by includes date; otherwise omit it.; enum: day|week|month Type: `string`. Optional. ```bash title="terminal" orc sources citations list --bucket-width ``` ##### `--classification-scope` Selects whether group_by=classification returns domain classifications or URL classifications.; enum: domain|host|url Type: `string`. Optional. ```bash title="terminal" orc sources citations list --classification-scope ``` ##### `--filter[hostname]` Comma-separated hostnames. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[hostname] ``` ##### `--filter[domain]` Comma-separated registrable domains; subdomains are normalized to their registrable domain. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[domain] ``` ##### `--filter[url]` Comma-separated URLs. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[url] ``` ##### `--filter[classification]` Comma-separated classification values. Matches any supplied value; omit to include all classifications. For citation aggregates, classification_scope selects the vocabulary. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[classification] ``` ##### `--filter[platform]` Comma-separated platform identifiers, such as openai or anthropic. Values are trimmed and lowercased. Matches any selected platform; omit or send an empty value for no platform filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[platform] ``` ##### `--filter[topic-id]` Comma-separated topic IDs for the answer population. Matches any selected topic in the workspace. Omit or send an empty value for no topic filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[topic-id] ``` ##### `--filter[brand-id]` Comma-separated IDs of the brands that own the answer prompts. Matches any selected parent brand in the workspace; this does not select every brand mentioned in an answer. Omit for no parent-brand filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[brand-id] ``` ##### `--filter[tag]` Comma-separated prompt tag names, not tag IDs. Values are trimmed and lowercased. Matches any selected name. Omit or send an empty value for no tag filter. Combines with other filter fields using AND. Type: `string`. Optional. ```bash title="terminal" orc sources citations list --filter[tag] ``` ## Examples ### Compare growing sources over a fixed interval. ```bash title="terminal" orc sources domains list --cohort trending --start-date 2026-09-01 --end-date 2026-09-30 ``` *Compare growing sources over a fixed interval.* ### Retrieve daily citation aggregates. ```bash title="terminal" orc sources citations list --group-by date,domain --bucket-width day --json ``` *Retrieve daily citation aggregates.* ### Inspect competitor gaps by URL. ```bash title="terminal" orc sources gaps list --view url --min-competitors 2 ``` *Inspect competitor gaps by URL.* ## Filter targets Comma-separated platform, topic, brand, and tag values match any value within the same field; different fields combine with AND. Brand means the brand owning answer prompts, not any mentioned brand. Tags are names, not IDs. Domain filters normalize subdomains to their registrable domain. Match classification values to the view and scope. ## 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 sources`: - [`--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)