​

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.

List source domains.

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.

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.

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.

Minimum distinct configured competitors found in an answer.

Type: number. Optional.

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

Type: string. Optional.

Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound.

Type: string. Optional.

Case-insensitive source hostname, URL, or title search.

Type: string. Optional.

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.

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.

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.

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.

Comma-separated competitor Brand IDs that must be mentioned in qualifying answers.

Type: string. Optional.

Comma-separated ISO 3166-1 alpha-2 country codes for qualifying prompts.

Type: string. Optional.

Whether any or all selected mentioned Brand IDs must occur in a qualifying answer.; enum: or|and

Type: string. Optional.

Comma-separated SourceDomainClassification values.

Type: string. Optional.

Comma-separated SourceUrlClassification values.

Type: string. Optional.

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.

Sort direction.; enum: asc|desc

Type: string. Optional.

One-based page number. Defaults to 1; values above 100000 are capped. Reuse the same filters when incrementing the page.

Type: number. Optional.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

One-based page number. Defaults to 1; values above 100000 are capped. Reuse the same filters when incrementing the page.

Type: number. Optional.

Retrieve details using a source-domain hostname returned by the host-view list. Distinguish it from a domain rollup display value.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Comma-separated classification values. Matches any supplied value; omit to include all classifications. For citation aggregates, classification_scope selects the vocabulary.

Type: string. Optional.

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.

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.

Retrieve details with the URL-encoded source URL returned by listing. It does not register a new source or request a URL crawl.

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.

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.

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

Type: string. Optional.

Inclusive UTC end date (YYYY-MM-DD). Omit for no upper bound.

Type: string. Optional.

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.

Calendar date bucket width. Required when group_by includes date; otherwise omit it.; enum: day|week|month

Type: string. Optional.

Selects whether group_by=classification returns domain classifications or URL classifications.; enum: domain|host|url

Type: string. Optional.

Comma-separated hostnames.

Type: string. Optional.

Comma-separated registrable domains; subdomains are normalized to their registrable domain.

Type: string. Optional.

Comma-separated URLs.

Type: string. Optional.

Comma-separated classification values. Matches any supplied value; omit to include all classifications. For citation aggregates, classification_scope selects the vocabulary.

Type: string. Optional.

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.

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.

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.

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.

Compare growing sources over a fixed interval.

Retrieve daily citation aggregates.

Inspect competitor gaps by URL.

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.

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

The following global options can be used with orc sources:

For details and examples, see global options.