> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentlinkops.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read competitor backlink evidence

> Read retained competitor backlinks with separate source check, page evidence and AI assessment results.

`get_competitor_analysis_candidates`

Read retained competitor backlinks with separate source check, page evidence and AI assessment results. Keep the retrieval revision and pass outcomeRevision across pages for consistent evidence. Reading does not fetch pages, run checks, buy data or start monitoring.

<Note>This command name is absent from deployment evidence dated 2026-10-16. Hosted availability for this current definition is unverified; inspect your connected catalog before invoking it. Verify the command and its input schema in the selected environment.</Note>

| Access | Behavior |
| - | - |
| `discovery:read`, `watches:read` | Reads saved data |

This read does not start a verification job.

## Example request

Connect through [MCP](/guides/connect-mcp), [CLI](/guides/connect-cli), or [HTTP](/guides/connect-http). Replace example identifiers with records from your workspace.

<CodeGroup>
  ```json MCP theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_competitor_analysis_candidates",
      "arguments": {
        "analysisId": "ca_example",
        "evidenceRevision": 1,
        "limit": 100
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call get_competitor_analysis_candidates --args '{"analysisId":"ca_example","evidenceRevision":1,"limit":100}'
  ```

  ```bash HTTP theme={null}
  curl --fail-with-body https://app.agentlinkops.com/v1/commands/get_competitor_analysis_candidates \
    -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data '{"analysisId":"ca_example","evidenceRevision":1,"limit":100}'
  ```
</CodeGroup>

## Returned result

Illustrative data validated against the documented response schema. IDs and dates are examples, not a live account capture. MCP returns this data in `structuredContent` and in a text content block; generic HTTP and CLI return the JSON result directly.

<Accordion title="Full response example">
  ```json theme={null}
  {
    "snapshot": {
      "version": "competitor-inventory-v2",
      "id": "retrieval_example_1",
      "retrieval_id": "retrieval_example",
      "analysis_id": "ca_example",
      "workspace_id": "ws_example",
      "project_id": "pr_example",
      "competitor_binding": {
        "set_id": "cs_example",
        "set_revision": 1,
        "member_id": "cm_example"
      },
      "provider": "dataforseo",
      "data_mode": "provider_index",
      "rank_scale": "one_thousand",
      "target": "rival.example.org",
      "include_subdomains": true,
      "query_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "evidence_revision": 1,
      "state": "complete",
      "coverage": "complete_provider_query",
      "partial_reason": null,
      "pages": 1,
      "returned_rows": 0,
      "accepted_candidates": 0,
      "rejected_rows": 0,
      "duplicate_rows": 0,
      "provider_total_count": 0,
      "created_at": "2026-09-13T12:00:00.000Z",
      "retrieved_at": "2026-09-13T12:00:00.000Z",
      "expires_at": "2026-11-01T00:00:00.000Z"
    },
    "items": [],
    "next_cursor": null,
    "outcome_revision": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  }
  ```
</Accordion>

## Input fields

Omit optional fields when you do not want to supply them. Null is accepted only where listed. Unknown input properties are rejected.

| Field | Type | Presence | Meaning and constraints |
| - | - | - | - |
| `analysisId` | string | Required | Saved competitor analysis ID. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
| `evidenceRevision` | integer | Required | Retained retrieval evidence revision from the saved analysis. Keep this revision for every page. maximum: `9007199254740991`; exclusiveMinimum: `0` |
| `cursor` | string | Optional | Continuation cursor returned for this retrieval snapshot. Omit for its first page. minLength: `1`; maxLength: `1024` |
| `limit` | integer | Optional | Maximum candidates per page, from 1 to 100. Defaults to 100. minimum: `1`; maximum: `100`; default: `100` |
| `outcomeRevision` | string | Optional | Outcome revision returned by the first page. Pass it on later pages to reject changed check or assessment evidence. pattern: `"^[a-f0-9]{64}$"` |

### Validation and omitted values

Reads saved backlinks and separate source check, page evidence and AI assessment outcomes. Reading does not fetch pages, run checks, buy data or create recurring monitoring.

Keep evidenceRevision for every page. To keep check and assessment evidence consistent, pass the first response outcome\_revision as outcomeRevision on later pages. If that evidence changes, restart from the saved analysis.

Provider metrics retain their native scales and dates. Missing checks or assessments remain unknown; supplier flags do not confirm current link presence.

### Defaults when omitted

| Field | Default |
| - | - |
| `limit` | `100` |

## Output fields

Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](/reference/schemas) explain evidence states, empty lists and extensions.

* **`snapshot`** (object, required): additional fields rejected
* **`items`** (array, required): Records in this bounded page. maxItems: `100`
* **`next_cursor`** (string / null, required): Opaque continuation for the same listing; null means no further page.
* **`outcome_revision`** (string, required): pattern: `"^[a-f0-9]{64}$"`

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `snapshot` | object | Required | additional fields rejected |
  | `snapshot.version` | string | Required | must equal `"competitor-inventory-v2"` |
  | `snapshot.id` | string | Required | Resource identifier returned by the operation. pattern: `"^[a-zA-Z0-9_-]{1,160}$"` |
  | `snapshot.retrieval_id` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.analysis_id` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.workspace_id` | string | Required | Workspace that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.project_id` | string | Required | Project that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.competitor_binding` | object | Required | additional fields rejected |
  | `snapshot.competitor_binding.set_id` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.competitor_binding.set_revision` | integer | Required | maximum: `9007199254740991`; exclusiveMinimum: `0` |
  | `snapshot.competitor_binding.member_id` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `snapshot.provider` | string | Required | must equal `"dataforseo"` |
  | `snapshot.data_mode` | string | Required | must equal `"provider_index"` |
  | `snapshot.rank_scale` | string | Required | must equal `"one_thousand"` |
  | `snapshot.target` | string | Required | |
  | `snapshot.include_subdomains` | boolean | Required | |
  | `snapshot.query_hash` | string | Required | pattern: `"^[a-f0-9]{64}$"` |
  | `snapshot.evidence_revision` | integer | Required | maximum: `9007199254740991`; exclusiveMinimum: `0` |
  | `snapshot.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"pending"`, `"complete"`, `"partial"` |
  | `snapshot.coverage` | string | Required | Dataset scope and completeness, including limits on what these results establish. values: `"complete_provider_query"`, `"partial_provider_query"` |
  | `snapshot.partial_reason` | string / null | Required | |
  | `snapshot.pages` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.returned_rows` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.accepted_candidates` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.rejected_rows` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.duplicate_rows` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.provider_total_count` | integer / null | Required | |
  | `snapshot.created_at` | string | Required | UTC timestamp when the record was created. format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `snapshot.retrieved_at` | string | Required | format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `snapshot.expires_at` | string | Required | format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `items` | array | Required | Records in this bounded page. maxItems: `100` |
  | `items[].v` | number | Required | must equal `1` |
  | `items[].id` | string | Required | Resource identifier returned by the operation. pattern: `"^dc_[a-f0-9]{64}$"` |
  | `items[].workspace_id` | string | Required | Workspace that owns this record. minLength: `1`; maxLength: `128`; pattern: `"^[a-zA-Z0-9_-]+$"` |
  | `items[].project_id` | string | Required | Project that owns this record. minLength: `1`; maxLength: `128`; pattern: `"^[a-zA-Z0-9_-]+$"` |
  | `items[].discovery_run_id` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `128`; pattern: `"^[a-zA-Z0-9_-]+$"` |
  | `items[].source_url` | string | Required | Publisher page URL recorded in this evidence. maxLength: `4096` |
  | `items[].target_url` | string | Required | Destination URL recorded in this evidence. maxLength: `4096` |
  | `items[].provider` | string | Required | values: `"linktrail_corpus"`, `"dataforseo"`, `"imported"` |
  | `items[].data_mode` | string | Required | values: `"synthetic"`, `"owned_corpus"`, `"provider_index"`, `"imported"` |
  | `items[].provider_task_id` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `128`; pattern: `"^[a-zA-Z0-9_-]+$"` |
  | `items[].provider_retrieved_at` | string | Required | Timestamp when the upstream evidence was retrieved. format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `items[].provider_first_seen` | string / null | Required | |
  | `items[].provider_prev_seen` | string / null | Required | |
  | `items[].provider_last_seen` | string / null | Required | |
  | `items[].provider_status` | object | Required | additional fields rejected |
  | `items[].provider_status.is_lost` | boolean / null | Required | |
  | `items[].provider_status.is_broken` | boolean / null | Required | |
  | `items[].provider_status.is_new` | boolean / null | Required | |
  | `items[].anchor` | string / null | Required | |
  | `items[].rel` | array / null | Required | |
  | `items[].dofollow` | boolean / null | Required | |
  | `items[].link_type` | string / null | Required | |
  | `items[].source_http_status` | integer / null | Required | |
  | `items[].target_http_status` | integer / null | Required | |
  | `items[].links_count` | integer / null | Required | |
  | `items[].provider_metrics` | object / object / object | Required | |
  | `items[].provider_metrics.dataforseo` | object | Required | additional fields rejected |
  | `items[].provider_metrics.dataforseo.rank` | integer / null | Required | |
  | `items[].provider_metrics.dataforseo.page_from_rank` | integer / null | Required | |
  | `items[].provider_metrics.dataforseo.domain_from` | string | Optional | minLength: `1`; maxLength: `253` |
  | `items[].provider_metrics.dataforseo.domain_from_rank` | integer / null | Required | |
  | `items[].provider_metrics.dataforseo.backlink_spam_score` | integer / null | Required | |
  | `items[].provider_metrics.dataforseo.rank_scale` | string | Required | must equal `"one_thousand"` |
  | `items[].provider_metrics.imported` | object | Required | additional fields rejected |
  | `items[].provider_metrics.imported.supplier` | string | Required | values: `"ahrefs"`, `"google_search_console"`, `"bing_webmaster_tools"`, `"semrush"`, `"majestic"`, `"moz"`, `"dataforseo"`, `"linkody"`, `"csv"` |
  | `items[].provider_metrics.imported.supplier_row_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].provider_metrics.imported.target_basis` | string | Optional | values: `"supplier_observed"`, `"user_supplied_target_expectation"` |
  | `items[].provider_metrics.imported.supplier_generated_at` | string / null | Required | |
  | `items[].provider_metrics.imported.supplier_metrics` | object / null | Required | |
  | `items[].provider_metrics.linktrail_corpus` | object | Required | additional fields rejected |
  | `items[].provider_metrics.linktrail_corpus.source_outlink_count` | integer / null | Required | |
  | `items[].provider_metrics.linktrail_corpus.source_external_outlink_count` | integer / null | Required | |
  | `items[].provider_metrics.linktrail_corpus.fetch_kind` | string | Required | values: `"direct"`, `"rendered"`, `"proxied"` |
  | `items[].provider_metrics.linktrail_corpus.extraction_complete` | boolean | Required | |
  | `items[].verification_status` | string | Required | AgentLinkOps check state, independent of supplier flags. not\_checked means no AgentLinkOps check is recorded. values: `"not_checked"`, `"present"`, `"absent"`, `"unknown"`, `"source_unavailable"` |
  | `items[].verified_at` | string / null | Required | Timestamp of the AgentLinkOps check; null until checked. |
  | `items[].observation_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].evidence_id` | string / null | Required | Reference to retained evidence from the check. |
  | `items[].analysis` | object | Required | additional fields rejected |
  | `items[].analysis.source_check` | object | Required | additional fields rejected |
  | `items[].analysis.source_check.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"not_started"`, `"pending"`, `"running"`, `"completed"`, `"failed"`, `"unavailable"` |
  | `items[].analysis.source_check.verdict` | string / null | Required | |
  | `items[].analysis.source_check.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
  | `items[].analysis.source_check.checked_at` | string / null | Required | UTC timestamp of the saved check. |
  | `items[].analysis.source_check.job_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.occurrence_context` | object | Required | additional fields rejected |
  | `items[].analysis.occurrence_context.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"not_started"`, `"pending"`, `"completed"`, `"partial"`, `"failed"`, `"unavailable"`, `"previous"` |
  | `items[].analysis.occurrence_context.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
  | `items[].analysis.occurrence_context.capture_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.occurrence_context.occurrence_count` | integer / null | Required | |
  | `items[].analysis.assessment` | object | Required | additional fields rejected |
  | `items[].analysis.assessment.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"not_started"`, `"pending"`, `"completed"`, `"partial"`, `"failed"`, `"unavailable"`, `"previous"`, `"no_role"` |
  | `items[].analysis.assessment.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
  | `items[].analysis.assessment.category_contract` | string | Optional | Version of the shared table, API and export category projection. must equal `"link-category-v1"` |
  | `items[].analysis.assessment.chosen_category` | object | Optional | The saved choice and recorded account attribution. Cleared keeps the type empty; automatic permits eligible existing page evidence to supply the displayed category. Neither action reviews or starts AI work. |
  | `items[].analysis.assessment.chosen_category.intent` | string | Required | values: `"chosen"`, `"cleared"`, `"automatic"` |
  | `items[].analysis.assessment.chosen_category.id` | string / null | Required | Resource identifier returned by the operation. |
  | `items[].analysis.assessment.chosen_category.name` | string / null | Required | |
  | `items[].analysis.assessment.chosen_category.standard_name` | string / null | Required | |
  | `items[].analysis.assessment.chosen_category.actor_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.chosen_category.recorded_at` | string / null | Required | |
  | `items[].analysis.assessment.chosen_category.revision` | integer | Required | Saved label revision; pass as revision to set\_link\_type. Required for intent=automatic. minimum: `0`; maximum: `9007199254740991` |
  | `items[].analysis.assessment.chosen_category.deliberate_clear` | boolean | Required | |
  | `items[].analysis.assessment.page_assessment` | object | Optional | What retained page evidence says about link occurrences. Applicability separates current, previous, expired and unavailable evidence. Suggested is provisional; accepted\_manual requires a recorded review; accepted\_auto requires a qualified saved policy. |
  | `items[].analysis.assessment.page_assessment.status` | string | Required | Resource lifecycle status. values: `"ready"`, `"unavailable"` |
  | `items[].analysis.assessment.page_assessment.reason` | string | Required | Recorded explanation; null when no explanation applies. |
  | `items[].analysis.assessment.page_assessment.read_reason` | string / null | Required | |
  | `items[].analysis.assessment.page_assessment.explanation` | string | Required | |
  | `items[].analysis.assessment.page_assessment.applicability` | string | Required | |
  | `items[].analysis.assessment.page_assessment.binding` | object / null | Required | |
  | `items[].analysis.assessment.page_assessment.binding.workspaceId` | string | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.binding.projectId` | string | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.binding.watchId` | string | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.capture` | object / null | Required | |
  | `items[].analysis.assessment.page_assessment.capture.id` | string | Required | Resource identifier returned by the operation. |
  | `items[].analysis.assessment.page_assessment.capture.manifest_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.capture.observation_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.capture.observed_at` | string / null | Required | UTC timestamp of the observation used here. |
  | `items[].analysis.assessment.page_assessment.capture.expires_at` | string / null | Required | |
  | `items[].analysis.assessment.page_assessment.source` | object / null | Required | |
  | `items[].analysis.assessment.page_assessment.source.state` | string / null | Required | Saved lifecycle or evidence state, as enumerated for this record. |
  | `items[].analysis.assessment.page_assessment.source.observed_at` | string / null | Required | UTC timestamp of the observation used here. |
  | `items[].analysis.assessment.page_assessment.source.observation_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.assessment.page_assessment.source.pageUnavailable` | boolean | Required | |
  | `items[].analysis.assessment.page_assessment.assessed_at` | string / null | Required | |
  | `items[].analysis.assessment.page_assessment.revision` | integer / null | Required | Highest retained eligible occurrence decision or review revision, or null. Evidence provenance, not a write token. |
  | `items[].analysis.assessment.page_assessment.model_revisions` | array | Required | |
  | `items[].analysis.assessment.page_assessment.model_revisions[].model` | string | Required | |
  | `items[].analysis.assessment.page_assessment.model_revisions[].revision` | string / null | Required | Recorded model version or revision, or null. Evidence provenance, not a write token. |
  | `items[].analysis.assessment.page_assessment.policy_revisions` | array | Required | |
  | `items[].analysis.assessment.page_assessment.policy_revisions[].taxonomy_version` | string / null | Required | |
  | `items[].analysis.assessment.page_assessment.policy_revisions[].rubric_version` | string / null | Required | |
  | `items[].analysis.assessment.page_assessment.policy_revisions[].policy_revision` | string / number / null | Required | Recorded policy revision as a string or number, or null. Evidence provenance, not a write token. |
  | `items[].analysis.assessment.page_assessment.roles` | array | Required | |
  | `items[].analysis.assessment.page_assessment.roles[].id` | string | Required | Resource identifier returned by the operation. values: `"contextual_citation"`, `"guest_post"`, `"recommendation"`, `"resource_entry"`, `"technical_reference"`, `"directory_entry"`, `"profile_website"`, `"author_attribution"`, `"discussion_contribution"`, `"navigation_template"`, `"badge_embed_attribution"`, `"partner_sponsor"`, `"other"` |
  | `items[].analysis.assessment.page_assessment.roles[].name` | string | Required | |
  | `items[].analysis.assessment.page_assessment.roles[].standard_name` | string | Required | |
  | `items[].analysis.assessment.page_assessment.roles[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items[].analysis.assessment.page_assessment.roles[].states` | object | Required | |
  | `items[].analysis.assessment.page_assessment.roles[].states.suggested` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items[].analysis.assessment.page_assessment.roles[].states.accepted_manual` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items[].analysis.assessment.page_assessment.roles[].states.accepted_auto` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items[].analysis.assessment.page_assessment.decision_state` | string | Required | values: `"suggested"`, `"accepted_manual"`, `"accepted_auto"`, `"mixed"`, `"none"` |
  | `items[].analysis.assessment.page_assessment.mixed` | boolean | Required | |
  | `items[].analysis.assessment.page_assessment.coverage` | object | Required | Occurrence counts for this watch. Null means unavailable. Assessed counts completed evaluations, including inconclusive ones. Classified counts occurrences with a determined role; partial describes type coverage. Retained includes excluded occurrences. Counts do not represent separate watched links. |
  | `items[].analysis.assessment.page_assessment.coverage.assessed` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.classified` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.eligible` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.retained` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.excluded` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.unassessed` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.unclassified` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.coverage.partial` | boolean / null | Required | |
  | `items[].analysis.assessment.page_assessment.pending_count` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.failed_count` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.job_count` | integer / null | Required | |
  | `items[].analysis.assessment.page_assessment.review_required_count` | integer / null | Required | |
  | `items[].analysis.assessment.display_category` | object | Optional | The category shown in the everyday table. A deliberate saved choice takes precedence. Otherwise page evidence supplies a category or Mixed types, with its evidence state. Read the reason when no category is available. |
  | `items[].analysis.assessment.display_category.source` | string | Required | values: `"chosen"`, `"page_assessment"`, `"none"` |
  | `items[].analysis.assessment.display_category.kind` | string | Required | values: `"category"`, `"mixed"`, `"cleared"`, `"unknown"` |
  | `items[].analysis.assessment.display_category.id` | string / null | Required | Resource identifier returned by the operation. |
  | `items[].analysis.assessment.display_category.name` | string | Required | |
  | `items[].analysis.assessment.display_category.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
  | `items[].analysis.assessment.display_category.reason` | string | Required | Recorded explanation; null when no explanation applies. |
  | `items[].analysis.assessment.display_category.applicability` | string | Required | |
  | `items[].analysis.assessment.display_category.coverage` | object | Required | Occurrence counts for this watch. Null means unavailable. Assessed counts completed evaluations, including inconclusive ones. Classified counts occurrences with a determined role; partial describes type coverage. Retained includes excluded occurrences. Counts do not represent separate watched links. |
  | `items[].analysis.assessment.display_category.coverage.assessed` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.classified` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.eligible` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.retained` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.excluded` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.unassessed` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.unclassified` | integer / null | Required | |
  | `items[].analysis.assessment.display_category.coverage.partial` | boolean / null | Required | |
  | `items[].analysis.watch_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].analysis.google_index` | object | Required | additional fields rejected |
  | `items[].analysis.google_index.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. must equal `"unavailable"` |
  | `items[].analysis.google_index.reason` | string | Required | Recorded explanation; null when no explanation applies. must equal `"COMPETITOR_PROPERTY_ACCESS_UNAVAILABLE"` |
  | `items[].analysis.recurring_monitoring_created` | boolean | Required | Whether this operation enrolled recurring monitoring. must equal `false` |
  | `next_cursor` | string / null | Required | Opaque continuation for the same listing; null means no further page. |
  | `outcome_revision` | string | Required | pattern: `"^[a-f0-9]{64}$"` |
</Accordion>

[Download input schema](/schemas/get_competitor_analysis_candidates.input.json) · [Download output schema](/schemas/get_competitor_analysis_candidates.output.json)

## Errors and retries

Follow the error recovery before retrying this read. Preserve the selected workspace, project, filters and feed. Recovering a read does not require an idempotency key or another verification job. Operation-specific errors include `COMPETITOR_PAGINATION_UNAVAILABLE`, `COMPETITOR_CHECKS_UNAVAILABLE`, `COMPETITOR_RETRIEVAL_NOT_FOUND`, `COMPETITOR_RETRIEVAL_EXPIRED`, `COMPETITOR_RETRIEVAL_AUTHORITY_CHANGED`, `COMPETITOR_CHECK_AUTHORITY_CHANGED`, `COMPETITOR_INVENTORY_NOT_READY`, `INVALID_COMPETITOR_INVENTORY_CURSOR`, `COMPETITOR_ANALYSIS_EVIDENCE_CHANGED`.

See [error recovery](/reference/errors) for status, scope, cooldown, cursor and retry handling. Unknown observations are result data and do not establish loss.

## HTTP resource routes

This operation has no separate resource alias. Use its generic command route in a matching environment.

## Continue

[get\_competitor\_analysis](/reference/commands/get_competitor_analysis)

Follow the [related workflow](/guides/competitor-research), inspect [capability status](/capability-status), or return to the [command index](/reference/index).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.