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

# Control a website scan

> Pause, cancel or explicitly resume a website scan using its current control revision.

`control_internal_link_scan`

Pause, cancel or explicitly resume a website scan using its current control revision. Resume records current authority; it does not install recurrence.

<Note>This command name appears in deployment evidence dated 2026-10-16. This page describes current source; read your connected catalog for deployed inputs and access. Workspace scopes and enabled providers still apply.</Note>

| Access | Behavior |
| - | - |
| `watches:write`, `watches:read` | 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": "control_internal_link_scan",
      "arguments": {
        "projectId": "prj_example",
        "scanId": "ilr_example",
        "action": "pause",
        "revision": 0
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call control_internal_link_scan --args '{"projectId":"prj_example","scanId":"ilr_example","action":"pause","revision":0}'
  ```

  ```bash HTTP theme={null}
  curl --fail-with-body https://app.agentlinkops.com/v1/commands/control_internal_link_scan \
    -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data '{"projectId":"prj_example","scanId":"ilr_example","action":"pause","revision":0}'
  ```
</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}
  {
    "scan": {
      "version": "internal-link-scan-v1",
      "id": "ilr_example",
      "projectId": "prj_example",
      "domain": "example.com",
      "homepage": "https://example.com/",
      "state": "paused",
      "reason": null,
      "createdAt": "2026-10-15T12:00:00.000Z",
      "updatedAt": "2026-10-15T12:00:00.000Z",
      "expiresAt": "2026-11-14T12:00:00.000Z",
      "completedAt": null,
      "revision": 1,
      "controlRevision": 1,
      "discoveredCount": 1,
      "completeCount": 0,
      "unknownCount": 0,
      "pendingCount": 1,
      "admittedCount": 0,
      "edgeCount": 0,
      "excludedReferences": 0,
      "exclusions": {},
      "nextEligibleAt": "2026-10-15T12:00:00.000Z",
      "discovery": {
        "state": "pending"
      },
      "coverage": {
        "inventory": "partial",
        "completeSiteCensus": false,
        "representation": "raw_html",
        "frontierTruncated": false,
        "renderedVisibility": false,
        "canonicalAliasesMerged": false
      },
      "usage": {
        "unit": "admitted_page",
        "period": "2026-10-15",
        "limit": 300,
        "used": 0,
        "resetsAt": "2026-10-16T00:00:00.000Z"
      }
    },
    "limits": {
      "pagesPerRun": 300,
      "workspacePagesPerDay": 300,
      "retainedRunsAndSnapshotsPerProject": 20,
      "retentionDays": 30,
      "pageBytes": 2097152,
      "pageTimeoutMs": 20000,
      "leaseMs": 90000,
      "maxAttempts": 3,
      "edgesPerPage": 200,
      "pageSize": 100
    }
  }
  ```
</Accordion>

## Input fields

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

| Field | Type | Presence | Meaning and constraints |
| - | - | - | - |
| `projectId` | string | Required | project ID from create/list. minLength: `1`; maxLength: `200` |
| `scanId` | string | Required | scan ID from create/list. minLength: `1`; maxLength: `200` |
| `action` | string | Required | action; see schema. values: `"pause"`, `"resume"`, `"cancel"` |
| `revision` | integer | Required | Current controlRevision from get\_internal\_link\_scan; this is separate from the evidence revision. minimum: `0`; maximum: `9007199254740991` |

### Validation and omitted values

Pass controlRevision from the current scan as revision. Pause and cancel prevent further scan publication; resume records current permission and does not create recurrence.

A daily allowance limit requires an explicit resume after reset. A scan at its page ceiling cannot resume; its saved evidence remains readable.

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

* **`scan`** (object, required): additional fields rejected
* **`limits`** (object, required): additional fields rejected

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `scan` | object | Required | additional fields rejected |
  | `scan.version` | string | Required | must equal `"internal-link-scan-v1"` |
  | `scan.id` | string | Required | Resource identifier returned by the operation. minLength: `1`; maxLength: `200` |
  | `scan.projectId` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
  | `scan.domain` | string | Required | |
  | `scan.homepage` | string | Required | |
  | `scan.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"queued"`, `"running"`, `"paused"`, `"cancelled"`, `"complete"`, `"limit_reached"`, `"failed"` |
  | `scan.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
  | `scan.createdAt` | string | Required | |
  | `scan.updatedAt` | string | Required | |
  | `scan.expiresAt` | string | Required | |
  | `scan.completedAt` | string / null | Required | |
  | `scan.revision` | integer | Required | Optimistic concurrency revision; supply it as expectedRevision on the next write. minimum: `0`; maximum: `9007199254740991` |
  | `scan.controlRevision` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.discoveredCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.completeCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.unknownCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.pendingCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.admittedCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.edgeCount` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.excludedReferences` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.exclusions` | object | Required | |
  | `scan.nextEligibleAt` | string | Required | |
  | `scan.discovery` | object | Required | additional fields rejected |
  | `scan.discovery.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: `"pending"`, `"complete"` |
  | `scan.discovery.coverage` | object | Optional | Dataset scope and completeness, including limits on what these results establish. additional fields rejected |
  | `scan.discovery.coverage.completeSiteCensus` | boolean | Required | must equal `false` |
  | `scan.discovery.coverage.truncated` | boolean | Required | |
  | `scan.discovery.coverage.reasons` | array | Required | |
  | `scan.discovery.documents` | array | Optional | maxItems: `13` |
  | `scan.discovery.documents[].requestedUrl` | string | Required | |
  | `scan.discovery.documents[].finalUrl` | string / null | Required | |
  | `scan.discovery.documents[].checkedAt` | string | Required | |
  | `scan.discovery.documents[].sha256` | string / null | Required | |
  | `scan.discovery.documents[].status` | integer / null | Required | Resource lifecycle status. |
  | `scan.discovery.documents[].reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
  | `scan.discovery.documents[].kind` | string | Required | values: `"robots"`, `"index"`, `"urlset"`, `"unknown"` |
  | `scan.coverage` | object | Required | Dataset scope and completeness, including limits on what these results establish. additional fields rejected |
  | `scan.coverage.inventory` | string | Required | must equal `"partial"` |
  | `scan.coverage.completeSiteCensus` | boolean | Required | must equal `false` |
  | `scan.coverage.representation` | string | Required | must equal `"raw_html"` |
  | `scan.coverage.frontierTruncated` | boolean | Required | |
  | `scan.coverage.renderedVisibility` | boolean | Required | must equal `false` |
  | `scan.coverage.canonicalAliasesMerged` | boolean | Required | must equal `false` |
  | `scan.usage` | object | Required | additional fields rejected |
  | `scan.usage.unit` | string | Required | must equal `"admitted_page"` |
  | `scan.usage.period` | string | Required | |
  | `scan.usage.limit` | number | Required | must equal `300` |
  | `scan.usage.used` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `scan.usage.resetsAt` | string | Required | |
  | `limits` | object | Required | additional fields rejected |
  | `limits.pagesPerRun` | number | Required | must equal `300` |
  | `limits.workspacePagesPerDay` | number | Required | must equal `300` |
  | `limits.retainedRunsAndSnapshotsPerProject` | number | Required | must equal `20` |
  | `limits.retentionDays` | number | Required | must equal `30` |
  | `limits.pageBytes` | number | Required | must equal `2097152` |
  | `limits.pageTimeoutMs` | number | Required | must equal `20000` |
  | `limits.leaseMs` | number | Required | must equal `90000` |
  | `limits.maxAttempts` | number | Required | must equal `3` |
  | `limits.edgesPerPage` | number | Required | must equal `200` |
  | `limits.pageSize` | number | Required | must equal `100` |
</Accordion>

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

## Errors and retries

For control\_internal\_link\_scan, pass revision from the latest scan.controlRevision. After an uncertain response, read the saved state before deciding whether another action is needed. Refresh after SCAN\_CONTROL\_CONFLICT; do not blindly repeat an old control revision. Operation-specific errors include `INTERNAL_LINK_SCANS_UNAVAILABLE`, `INTERNAL_LINK_SCAN_EXPIRED`, `SCAN_CONTROL_CONFLICT`, `SCAN_FINISHED`, `SCAN_PAGE_LIMIT`, `INTERNAL_LINK_DAILY_LIMIT`, `INVALID_CURSOR`.

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 |
| - | - | - |
| `POST /v1/internal-links/scans/{scanId}/control` | 200 | The path sets scanId. Supply projectId, action and current controlRevision as revision in the JSON body. |

## Continue

[get\_internal\_link\_scan](/reference/commands/get_internal_link_scan)

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