> ## 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 rank history

> Read dated DataForSEO thousand-scale rank evidence and candidate-only alerts.

`list_rank_history`

Read dated DataForSEO thousand-scale rank evidence and candidate-only alerts. Unknown is not loss or zero.

<Note>Development preview. This command is absent from the verified deployed bundle. Use a matching development environment.</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_rank_history",
      "arguments": {
        "scheduleId": "rank_example",
        "limit": 50
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call list_rank_history --args '{"scheduleId":"rank_example","limit":50}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/list_rank_history" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"scheduleId":"rank_example","limit":50}'
  ```
</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.

```json theme={null}
{
  "schedule_id": "rank_example",
  "schedule_revision": 1,
  "project_id": "pr_example",
  "target": "example.com",
  "include_subdomains": true,
  "provider": "dataforseo",
  "data_mode": "synthetic",
  "metric": "rank",
  "scale": {
    "minimum": 0,
    "maximum": 1000,
    "name": "one_thousand"
  },
  "items": [],
  "alert_candidates": [],
  "has_more": false,
  "next_cursor": null
}
```

## Response formats

`format` selects the row shape. `detailed` is the example above: every field. `concise` keeps, per row: `overview_run_id`, `slot_at`, `rank`, `observed_at`, `retrieved_at`, `freshness`, `outcome`, `execution`, `cost`; 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 |
| - | - | - | - |
| `scheduleId` | string | Required | Identifier of the schedule returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `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

scheduleId is required. Retained synthetic attempts sort by slot time; limit ranges from one to 100. A preceding comparison record supports alert candidates without adding an extra returned item.

Use next\_cursor for the same schedule under current authority. Cursors bind to the schedule collection and current grants. INVALID\_CURSOR requires restarting that same listing without its cursor; config-only pause preserves the collection binding.

Rank uses the DataForSEO 0-1000 scale. Zero is a measured value; null denotes unknown evidence. observed\_at remains null, while retrieved\_at records retrieval time when known. The saved threshold determines freshness.

Execution and cost fields retain attempt and reconciliation facts. Missing evidence, stale evidence and unresolved cost do not establish a rank decrease or confirmed loss.

alert\_candidates carry delivery\_state candidate\_only. This read neither persists nor sends an alert and exposes no internal quotes, query hashes, leases or credential material.

History pages can change between calls. They do not provide a frozen full export, restore guarantee or live supplier acceptance.

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

* **`schedule_id`** (string, required): Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"
* **`schedule_revision`** (integer, required): maximum: 9007199254740991; exclusiveMinimum: 0
* **`project_id`** (string, required): Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"
* **`target`** (string, required): minLength: 1; maxLength: 253
* **`include_subdomains`** (boolean, required).
* **`provider`** (string, required): must equal "dataforseo"
* **`data_mode`** (string, required): must equal "synthetic"
* **`metric`** (string, required): must equal "rank"
* **`scale`** (object, required): additional fields rejected
* **`items`** (array, required): Records in this bounded page. maxItems: 100
* **`alert_candidates`** (array, required): maxItems: 100
* **`has_more`** (boolean, required): True when another page is available.
* **`next_cursor`** (string / null, required): Opaque continuation for the same listing; null means no further page.

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `schedule_id` | string | Required | Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `schedule_revision` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
  | `project_id` | string | Required | Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `target` | string | Required | minLength: 1; maxLength: 253 |
  | `include_subdomains` | boolean | Required | |
  | `provider` | string | Required | must equal "dataforseo" |
  | `data_mode` | string | Required | must equal "synthetic" |
  | `metric` | string | Required | must equal "rank" |
  | `scale` | object | Required | additional fields rejected |
  | `scale.minimum` | number | Required | must equal 0 |
  | `scale.maximum` | number | Required | must equal 1000 |
  | `scale.name` | string | Required | must equal "one\_thousand" |
  | `items` | array | Required | Records in this bounded page. maxItems: 100 |
  | `items[].overview_run_id` | string | Required | Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `items[].slot_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[].rank` | integer / null | Required | |
  | `items[].observed_at` | null | Required | UTC timestamp of the observation used here. |
  | `items[].retrieved_at` | string / null | Required | |
  | `items[].freshness` | string | Required | values: "unknown", "stale", "fresh" |
  | `items[].outcome` | string | Required | values: "unknown", "measured" |
  | `items[].execution` | object | Required | additional fields rejected |
  | `items[].execution.status` | string | Required | Resource lifecycle status. values: "queued", "running", "succeeded", "failed", "reconciliation\_required" |
  | `items[].execution.error_code` | string / null | Required | Latest delivery detail code; null when no failure or retry has been recorded. |
  | `items[].execution.provider_task_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].cost` | object | Required | additional fields rejected |
  | `items[].cost.currency` | string | Required | must equal "USD" |
  | `items[].cost.max_cost_microusd` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
  | `items[].cost.reserved_cost_microusd` | integer | Required | minimum: 0; maximum: 9007199254740991 |
  | `items[].cost.provider_reported_cost_microusd` | integer / null | Required | |
  | `items[].cost.request_count` | integer | Required | minimum: 0; maximum: 9007199254740991 |
  | `items[].cost.reconciliation_required` | boolean | Required | |
  | `alert_candidates` | array | Required | maxItems: 100 |
  | `alert_candidates[].id` | string | Required | Resource identifier returned by the operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `alert_candidates[].schedule_id` | string | Required | Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `alert_candidates[].provider` | string | Required | must equal "dataforseo" |
  | `alert_candidates[].metric` | string | Required | must equal "rank" |
  | `alert_candidates[].rank_scale` | string | Required | must equal "one\_thousand" |
  | `alert_candidates[].previous_run_id` | string | Required | Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `alert_candidates[].current_run_id` | string | Required | Identifier returned by the related operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `alert_candidates[].previous_rank` | integer | Required | minimum: 0; maximum: 1000 |
  | `alert_candidates[].current_rank` | integer | Required | minimum: 0; maximum: 1000 |
  | `alert_candidates[].change` | integer | Required | minimum: -1000; maximum: 1000 |
  | `alert_candidates[].observed_at` | null | Required | UTC timestamp of the observation used here. |
  | `alert_candidates[].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))\$" |
  | `alert_candidates[].delivery_state` | string | Required | must equal "candidate\_only" |
  | `has_more` | boolean | Required | True when another page is available. |
  | `next_cursor` | string / null | Required | Opaque continuation for the same listing; null means no further page. |
</Accordion>

[Download input schema](/schemas/list_rank_history.input.json) · [Download output schema](/schemas/list_rank_history.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

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

## Continue

[list\_rank\_history](/reference/commands/list_rank_history) · [get\_rank\_schedule](/reference/commands/get_rank_schedule)

Follow the [related workflow](/guides/monitor-changes), 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.