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

# List discovery candidates

> Read up to 100 candidates from an existing saved or imported run, including when new discovery admission is disabled.

`list_discovery_candidates`

Read up to 100 candidates from an existing saved or imported run, including when new discovery admission is disabled. Returns stored discovery candidates with dated provider provenance and separate verification status. Cursor pages freeze a stored result snapshot; restart without a cursor for newer results. Reads never purchase provider pages.

<Note>Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.</Note>

| Access           | Behavior         |
| ---------------- | ---------------- |
| `discovery: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": "list_discovery_candidates",
      "arguments": {
        "runId": "run_example"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call list_discovery_candidates --args '{"runId":"run_example"}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/list_discovery_candidates" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"runId":"run_example"}'
  ```
</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}
  {
    "items": [
      {
        "v": 1,
        "id": "dc_bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "workspace_id": "ws_example",
        "project_id": "pr_example",
        "discovery_run_id": "run_example",
        "source_url": "https://publisher.example.org/article",
        "target_url": "https://example.com/",
        "provider": "linktrail_corpus",
        "data_mode": "owned_corpus",
        "provider_retrieved_at": "2026-09-13T12:00:00.000Z",
        "provider_first_seen": "2026-09-13T12:00:00.000Z",
        "provider_prev_seen": null,
        "provider_last_seen": "2026-09-13T12:00:00.000Z",
        "provider_status": {
          "is_lost": null,
          "is_broken": null,
          "is_new": null
        },
        "anchor": "Example",
        "rel": [],
        "dofollow": true,
        "link_type": "anchor",
        "source_http_status": 200,
        "target_http_status": null,
        "links_count": 1,
        "provider_metrics": {
          "linktrail_corpus": {
            "source_outlink_count": 1,
            "source_external_outlink_count": 1,
            "fetch_kind": "direct",
            "extraction_complete": true
          }
        },
        "verification_status": "not_checked",
        "verified_at": null,
        "observation_id": null
      }
    ],
    "next_cursor": null,
    "has_more": false,
    "run": {
      "v": 1,
      "id": "run_example",
      "workspace_id": "ws_example",
      "project_id": "pr_example",
      "provider": "linktrail_corpus",
      "data_mode": "owned_corpus",
      "query": {
        "target_kind": "domain",
        "target": "example.com",
        "include_subdomains": true,
        "backlinks_status_type": "live",
        "exclude_internal_backlinks": true,
        "mode": "as_is",
        "filters": null,
        "order_by": [
          "first_seen,desc"
        ],
        "rank_scale": null,
        "page_limit": 100,
        "row_limit": 100
      },
      "status": "succeeded",
      "created_at": "2026-09-13T12:00:00.000Z",
      "started_at": "2026-09-13T12:00:00.000Z",
      "finished_at": "2026-09-13T12:00:00.000Z",
      "coverage": "complete_for_query",
      "coverage_reason": null,
      "provider_total_count": 1,
      "usage": {
        "unit": "discovery",
        "currency": "USD",
        "quote_id": "owned_example",
        "max_cost_microusd": 0,
        "reserved_cost_microusd": 0,
        "provider_reported_cost_microusd": 0,
        "request_count": 1,
        "returned_rows": 1,
        "accepted_candidates": 1,
        "rejected_rows": 0,
        "duplicate_rows": 0
      },
      "operation": "backlinks",
      "coverage_scope": "corpus_subset",
      "whole_web_coverage": false
    },
    "snapshot": {
      "through_provider_page": 0,
      "refresh_from_start_for_new_results": true
    }
  }
  ```
</Accordion>

## Response formats

`format` selects the row shape. `detailed` is the example above: every field. `concise` keeps, per row: `id`, `source_url`, `target_url`, `anchor`, `dofollow`, `provider_last_seen`, `verification_status`, `verified_at`, `observation_id`; every top-level field (cursors, counts, coverage, metadata) is kept in both. The observation state an unknown-versus-absent decision depends on is never dropped. MCP and code mode default to concise; the CLI and HTTP default to detailed; the response names the default it applied in `defaults_applied`.

## 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                                                                                                                                                                                                                                                                                          |
| -------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`  | string  | Required | Identifier of the run returned by its create or list operation. minLength: 1; maxLength: 200                                                                                                                                                                                                                     |
| `cursor` | string  | Optional | Opaque continuation returned by this same listing; omit for the first page. minLength: 1; maxLength: 1024                                                                                                                                                                                                        |
| `limit`  | integer | Optional | Maximum rows in this page or bounded report; subject to the schema maximum. minimum: 1; maximum: 100; default: 50                                                                                                                                                                                                |
| `format` | string  | Optional | Response shape: concise keeps the fields needed to decide and to call next (the evidence state always included); detailed returns every field. MCP and code mode default to concise; REST and the CLI to detailed. The response names the default it applied in defaults\_applied. values: "concise", "detailed" |

### Validation and omitted values

Omit cursor for the first page. Keep continuation cursors opaque and use them only with the same listing and filters.

Candidates are ordered by saved page index, then candidate identifier. The first page freezes a stored page ceiling; later pages do not include newly appended provider pages. Restart without a cursor for a newer snapshot.

### Defaults when omitted

| Field   | Default |
| ------- | ------- |
| `limit` | `50`    |

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

* **`items`** (array, required): Records in this bounded page.
* **`next_cursor`** (string / null, required): Opaque continuation for the same listing; null means no further page.
* **`has_more`** (boolean, optional): True when another page is available.
* **`admission`** (object / null, optional).
* **`run`** (object, required).
* **`snapshot`** (object, required).

<Accordion title="All fields and nested objects">
  | Field                                                                     | Type                     | Presence | Meaning and constraints                                                                                                                                                                                                                                                                                                                                                                      |
  | ------------------------------------------------------------------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `items`                                                                   | array                    | Required | Records in this bounded page.                                                                                                                                                                                                                                                                                                                                                                |
  | `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_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_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.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.                                                                                                                                                                                                                                                                                                                                                |
  | `next_cursor`                                                             | string / null            | Required | Opaque continuation for the same listing; null means no further page.                                                                                                                                                                                                                                                                                                                        |
  | `has_more`                                                                | boolean                  | Optional | True when another page is available.                                                                                                                                                                                                                                                                                                                                                         |
  | `admission`                                                               | object / null            | Optional |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.operation_id`                                                  | string                   | Required | Identifier returned by the related operation. minLength: 1; maxLength: 200                                                                                                                                                                                                                                                                                                                   |
  | `admission.project_id`                                                    | string                   | Required | Project that owns this record. minLength: 1; maxLength: 200                                                                                                                                                                                                                                                                                                                                  |
  | `admission.context`                                                       | string                   | Required | values: "import", "candidate", "candidate\_batch", "serve"                                                                                                                                                                                                                                                                                                                                   |
  | `admission.decisions`                                                     | array                    | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].index`                                             | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `admission.decisions[].url`                                               | string                   | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].normalized_url`                                    | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].host`                                              | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].decision`                                          | string                   | Required | values: "admitted", "rejected"                                                                                                                                                                                                                                                                                                                                                               |
  | `admission.decisions[].reason`                                            | string                   | Required | Recorded explanation; null when no explanation applies.                                                                                                                                                                                                                                                                                                                                      |
  | `admission.decisions[].rule_kind`                                         | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].rule_id`                                           | string / null            | Required | Identifier returned by the related operation.                                                                                                                                                                                                                                                                                                                                                |
  | `admission.decisions[].rule_value`                                        | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].cap`                                               | object / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.decisions[].cap.limit`                                         | integer                  | Required | maximum: 9007199254740991; exclusiveMinimum: 0                                                                                                                                                                                                                                                                                                                                               |
  | `admission.decisions[].cap.used`                                          | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `admission.decisions[].subject_key`                                       | string                   | Required | minLength: 1; maxLength: 200                                                                                                                                                                                                                                                                                                                                                                 |
  | `admission.summary`                                                       | object                   | Required | Grouped change counts included in this delivery, limited to accessible websites. additional fields rejected                                                                                                                                                                                                                                                                                  |
  | `admission.summary.total`                                                 | integer                  | Required | minimum: -9007199254740991; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                        |
  | `admission.summary.admitted`                                              | integer                  | Required | minimum: -9007199254740991; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                        |
  | `admission.summary.rejected`                                              | integer                  | Required | minimum: -9007199254740991; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                        |
  | `admission.summary.by_rule`                                               | object                   | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `admission.policy_revision`                                               | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `admission.disavow_revision`                                              | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `admission.replayed`                                                      | boolean                  | Required | True when the response reuses an earlier request with the same idempotency value.                                                                                                                                                                                                                                                                                                            |
  | `run`                                                                     | object                   | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.v`                                                                   | number                   | Required | must equal 1                                                                                                                                                                                                                                                                                                                                                                                 |
  | `run.id`                                                                  | string                   | Required | Resource identifier returned by the operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"                                                                                                                                                                                                                                                                                  |
  | `run.workspace_id`                                                        | string                   | Required | Workspace that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"                                                                                                                                                                                                                                                                                                |
  | `run.project_id`                                                          | string                   | Required | Project that owns this record. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"                                                                                                                                                                                                                                                                                                  |
  | `run.provider`                                                            | string                   | Required | values: "linktrail\_corpus", "dataforseo", "imported"                                                                                                                                                                                                                                                                                                                                        |
  | `run.data_mode`                                                           | string                   | Required | values: "synthetic", "owned\_corpus", "provider\_index", "imported"                                                                                                                                                                                                                                                                                                                          |
  | `run.query`                                                               | object                   | Required | additional fields rejected                                                                                                                                                                                                                                                                                                                                                                   |
  | `run.query.target_kind`                                                   | string                   | Required | values: "domain", "exact\_url"                                                                                                                                                                                                                                                                                                                                                               |
  | `run.query.target`                                                        | string                   | Required | minLength: 1; maxLength: 4096                                                                                                                                                                                                                                                                                                                                                                |
  | `run.query.include_subdomains`                                            | boolean                  | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.query.backlinks_status_type`                                         | string                   | Required | values: "live", "lost", "all"                                                                                                                                                                                                                                                                                                                                                                |
  | `run.query.exclude_internal_backlinks`                                    | boolean                  | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.query.mode`                                                          | string                   | Required | must equal "as\_is"                                                                                                                                                                                                                                                                                                                                                                          |
  | `run.query.filters`                                                       | null                     | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.query.order_by`                                                      | array                    | Required | minItems: 1; maxItems: 1                                                                                                                                                                                                                                                                                                                                                                     |
  | `run.query.rank_scale`                                                    | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.query.page_limit`                                                    | integer                  | Required | minimum: 1; maximum: 1000                                                                                                                                                                                                                                                                                                                                                                    |
  | `run.query.row_limit`                                                     | integer                  | Required | minimum: 1; maximum: 1000                                                                                                                                                                                                                                                                                                                                                                    |
  | `run.status`                                                              | string                   | Required | Resource lifecycle status. values: "queued", "running", "succeeded", "partial", "failed", "reconciliation\_required"                                                                                                                                                                                                                                                                         |
  | `run.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))\$"          |
  | `run.started_at`                                                          | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.finished_at`                                                         | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.coverage`                                                            | string                   | Required | Dataset scope and completeness, including limits on what these results establish. values: "pending", "complete\_for\_query", "capped", "partial", "unknown"                                                                                                                                                                                                                                  |
  | `run.coverage_reason`                                                     | string / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.provider_total_count`                                                | integer / null           | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.usage`                                                               | object                   | Required | additional fields rejected                                                                                                                                                                                                                                                                                                                                                                   |
  | `run.usage.unit`                                                          | string                   | Required | must equal "discovery"                                                                                                                                                                                                                                                                                                                                                                       |
  | `run.usage.currency`                                                      | string                   | Required | must equal "USD"                                                                                                                                                                                                                                                                                                                                                                             |
  | `run.usage.quote_id`                                                      | string                   | Required | Identifier returned by the related operation. minLength: 1; maxLength: 128; pattern: "^\[a-zA-Z0-9\_-]+\$"                                                                                                                                                                                                                                                                                   |
  | `run.usage.max_cost_microusd`                                             | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.reserved_cost_microusd`                                        | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.provider_reported_cost_microusd`                               | integer / null           | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `run.usage.request_count`                                                 | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.returned_rows`                                                 | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.accepted_candidates`                                           | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.rejected_rows`                                                 | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.usage.duplicate_rows`                                                | integer                  | Required | minimum: 0; maximum: 9007199254740991                                                                                                                                                                                                                                                                                                                                                        |
  | `run.operation`                                                           | string                   | Required | must equal "backlinks"                                                                                                                                                                                                                                                                                                                                                                       |
  | `run.coverage_scope`                                                      | string                   | Required | values: "customer\_import", "corpus\_subset", "provider\_query"                                                                                                                                                                                                                                                                                                                              |
  | `run.whole_web_coverage`                                                  | boolean                  | Required | False: these results do not measure the whole web. must equal false                                                                                                                                                                                                                                                                                                                          |
  | `run.replayed`                                                            | boolean                  | Optional | True when the response reuses an earlier request with the same idempotency value.                                                                                                                                                                                                                                                                                                            |
  | `snapshot`                                                                | object                   | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `snapshot.through_provider_page`                                          | number / null            | Required |                                                                                                                                                                                                                                                                                                                                                                                              |
  | `snapshot.refresh_from_start_for_new_results`                             | boolean                  | Required | must equal true                                                                                                                                                                                                                                                                                                                                                                              |
</Accordion>

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

## Errors and retries

The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.

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

These existing resource routes share the operation’s domain behavior. Their parameter placement, status and response envelope can differ from generic invocation. See [HTTP route details](/reference/http/routes).

| Method and route                            | Success | Details                                          |
| ------------------------------------------- | ------- | ------------------------------------------------ |
| `GET /v1/discovery/runs/{runId}/candidates` | 200     | Remaining read arguments go in query parameters. |

## Continue

[verify\_discovery\_candidate](/reference/commands/verify_discovery_candidate) · [verify\_discovery\_candidates](/reference/commands/verify_discovery_candidates)

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