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

# Create rank schedule

> Configure synthetic DataForSEO rank monitoring.

`create_rank_schedule`

Configure synthetic DataForSEO rank monitoring. Hosted enrollment is disabled; no supplier call or Ahrefs DR.

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

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": "create_rank_schedule",
      "arguments": {
        "scheduleId": "rank_example",
        "projectId": "project_example",
        "target": "example.com",
        "anchorAt": "2026-09-30T00:00:00.000Z"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call create_rank_schedule --args '{"scheduleId":"rank_example","projectId":"project_example","target":"example.com","anchorAt":"2026-09-30T00:00:00.000Z"}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/create_rank_schedule" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"scheduleId":"rank_example","projectId":"project_example","target":"example.com","anchorAt":"2026-09-30T00:00:00.000Z"}'
  ```
</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": "project_example",
  "collection_revision": 1,
  "config_version": 1,
  "provider": "dataforseo",
  "data_mode": "synthetic",
  "metric": "rank",
  "rank_scale": "one_thousand",
  "target": "example.com",
  "include_subdomains": true,
  "state": "active",
  "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": "synthetic",
    "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}\$" |
| `projectId` | string | Required | Identifier of the project returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `target` | string | Required | Exact URL or domain to query, interpreted according to targetKind. minLength: 1; maxLength: 253 |
| `includeSubdomains` | boolean | Optional | Include subdomains of the selected domain in this query. default: true |
| `anchorAt` | string | Required | The anchor at value; allowed values and bounds are specified in this schema. 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))\$" |
| `cadenceSeconds` | integer | Optional | Scheduled check interval in seconds, from 3600 to 2592000. minimum: 86400; maximum: 2592000; default: 604800 |
| `staleAfterSeconds` | integer | Optional | The stale after seconds value; allowed values and bounds are specified in this schema. minimum: 86400; maximum: 5184000; default: 1209600 |
| `alerts` | object | Optional | The alerts value; allowed values and bounds are specified in this schema. default: \{"enabled":false,"direction":"either","minimumChange":10}; 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

Hosted creation returns PROVIDER\_DISABLED. Synthetic creation requires a test-only injected capability; command arguments and environment flags cannot start collection.

Supply scheduleId, projectId, target and anchorAt. Cadence ranges from one to 30 days; freshness ranges from one to 60 days and must cover at least one cadence.

The stored metric is DataForSEO rank on its 0-1000 scale. Ahrefs DR and Moz scores use separate metrics. The fixed query includes indirect links, excludes internal backlinks and requests live backlink status.

A workspace holds at most 100 schedules. Reusing an accessible schedule ID requires identical configuration; changing target, subdomain policy, anchor or cadence requires a new schedule ID.

This development command makes no supplier request, sends no outreach and delivers no alerts.

### Defaults when omitted

| Field | Default |
| - | - |
| `includeSubdomains` | `true` |
| `cadenceSeconds` | `604800` |
| `staleAfterSeconds` | `1209600` |
| `alerts` | `{"enabled":false,"direction":"either","minimumChange":10}` |

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

[get\_rank\_schedule](/reference/commands/get_rank_schedule) · [list\_rank\_schedules](/reference/commands/list_rank_schedules)

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.