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

# Update rank schedule

> Pause or change rank settings with expectedVersion.

`update_rank_schedule`

Pause or change rank settings with expectedVersion. Hosted resume is disabled; history is retained.

<Note>Development preview. This command is absent from the verified deployed bundle. Use a matching development environment.</Note>

| Access | Behavior |
| - | - |
| `discovery:write` | Writes or admits work; can change or remove existing state |

This operation changes saved state. Review its inputs and retry behavior before calling.

## 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": "update_rank_schedule",
      "arguments": {
        "scheduleId": "rank_example",
        "expectedVersion": 1,
        "state": "paused"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call update_rank_schedule --args '{"scheduleId":"rank_example","expectedVersion":1,"state":"paused"}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/update_rank_schedule" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"scheduleId":"rank_example","expectedVersion":1,"state":"paused"}'
  ```
</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}
{
  "id": "rank_example",
  "project_id": "pr_example",
  "collection_revision": 1,
  "config_version": 2,
  "provider": "dataforseo",
  "data_mode": "synthetic",
  "metric": "rank",
  "rank_scale": "one_thousand",
  "target": "example.com",
  "include_subdomains": true,
  "state": "paused",
  "anchor_at": "2026-09-30T00:00:00.000Z",
  "cadence_seconds": 604800,
  "stale_after_seconds": 1209600,
  "alerts": {
    "enabled": false,
    "direction": "either",
    "minimum_change": 10
  },
  "last_admitted_slot": null,
  "created_at": "2026-09-30T00:00:00.000Z",
  "updated_at": "2026-09-30T00:00:00.000Z",
  "availability": {
    "collection": "disabled",
    "alert_delivery": "not_enabled"
  }
}
```

## 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}\$" |
| `expectedVersion` | integer | Required | The expected version value; allowed values and bounds are specified in this schema. maximum: 9007199254740991; exclusiveMinimum: 0 |
| `state` | string | Optional | Requested resource state or saved-observation filter, as enumerated here. values: "active", "paused" |
| `staleAfterSeconds` | integer | Optional | The stale after seconds value; allowed values and bounds are specified in this schema. minimum: 86400; maximum: 5184000 |
| `alerts` | object | Optional | The alerts value; allowed values and bounds are specified in this schema. additional fields rejected |
| `alerts.enabled` | boolean | Required | |
| `alerts.direction` | string | Required | values: "increase", "decrease", "either" |
| `alerts.minimumChange` | integer | Required | minimum: 1; maximum: 1000 |

### Validation and omitted values

Supply scheduleId, expectedVersion and at least one of state, staleAfterSeconds or alerts. Omitted settings retain their values. Supply all three fields when changing alerts.

On RANK\_SCHEDULE\_CONFLICT, read the schedule and review its current config\_version before retrying. A successful update increments config\_version and preserves collection slot identity.

Pausing preserves admitted history. Explicit state active returns PROVIDER\_DISABLED in hosted routing; repeated retries cannot start collection.

Target, subdomain policy, anchor and cadence are immutable. Freshness must cover at least one cadence. Alert settings describe candidate comparisons; alert\_delivery remains not\_enabled.

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

* **`id`** (string, required): Resource identifier returned by the operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"
* **`project_id`** (string, required): Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$"
* **`collection_revision`** (integer, required): maximum: 9007199254740991; exclusiveMinimum: 0
* **`config_version`** (integer, required): maximum: 9007199254740991; exclusiveMinimum: 0
* **`provider`** (string, required): must equal "dataforseo"
* **`data_mode`** (string, required): must equal "synthetic"
* **`metric`** (string, required): must equal "rank"
* **`rank_scale`** (string, required): must equal "one\_thousand"
* **`target`** (string, required): minLength: 1; maxLength: 253
* **`include_subdomains`** (boolean, required).
* **`state`** (string, required): Saved lifecycle or evidence state, as enumerated for this record. values: "active", "paused"
* **`anchor_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))\$"
* **`cadence_seconds`** (integer, required): minimum: 86400; maximum: 2592000
* **`stale_after_seconds`** (integer, required): minimum: 86400; maximum: 5184000
* **`alerts`** (object, required): additional fields rejected
* **`last_admitted_slot`** (string / null, required).
* **`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))\$"
* **`updated_at`** (string, required): UTC timestamp of the last record update. 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))\$"
* **`availability`** (object, required): additional fields rejected

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `id` | string | Required | Resource identifier returned by the operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `project_id` | string | Required | Project that owns this record. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
  | `collection_revision` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
  | `config_version` | integer | Required | maximum: 9007199254740991; exclusiveMinimum: 0 |
  | `provider` | string | Required | must equal "dataforseo" |
  | `data_mode` | string | Required | must equal "synthetic" |
  | `metric` | string | Required | must equal "rank" |
  | `rank_scale` | string | Required | must equal "one\_thousand" |
  | `target` | string | Required | minLength: 1; maxLength: 253 |
  | `include_subdomains` | boolean | Required | |
  | `state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: "active", "paused" |
  | `anchor_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))\$" |
  | `cadence_seconds` | integer | Required | minimum: 86400; maximum: 2592000 |
  | `stale_after_seconds` | integer | Required | minimum: 86400; maximum: 5184000 |
  | `alerts` | object | Required | additional fields rejected |
  | `alerts.enabled` | boolean | Required | |
  | `alerts.direction` | string | Required | values: "increase", "decrease", "either" |
  | `alerts.minimum_change` | integer | Required | minimum: 1; maximum: 1000 |
  | `last_admitted_slot` | string / null | Required | |
  | `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))\$" |
  | `updated_at` | string | Required | UTC timestamp of the last record update. 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))\$" |
  | `availability` | object | Required | additional fields rejected |
  | `availability.collection` | string | Required | values: "disabled", "synthetic" |
  | `availability.alert_delivery` | string | Required | must equal "not\_enabled" |
</Accordion>

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

## Errors and retries

This command is not annotated idempotent. After a timeout, inspect existing state before repeating a write.

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\_rank\_schedule](/reference/commands/get_rank_schedule) · [list\_rank\_history](/reference/commands/list_rank_history)

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.