> ## 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 link watches
> List monitored placements with compact state and attempt summaries.
`list_link_watches`
List monitored placements with compact state and attempt summaries. Use include=detail or get\_link\_watch for occurrences and evidence.
Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. Workspace scopes and enabled providers still apply.
| Access | Behavior |
| -------------- | ---------------- |
| `watches: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.
```json MCP theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_link_watches",
"arguments": {}
}
}
```
```bash CLI theme={null}
agentlinkops call list_link_watches --args '{}'
```
```bash HTTP theme={null}
curl "$AGENTLINKOPS_API_URL/v1/commands/list_link_watches" \
-H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
-H 'Content-Type: application/json' \
--data '{}'
```
## 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}
{
"items": [
{
"workspace_id": "ws_example",
"project_id": "pr_example",
"status": "active",
"cadence_seconds": 86400,
"state": "unknown",
"observation_state": {},
"created_at": "2026-09-13T12:00:00.000Z",
"updated_at": "2026-09-13T12:00:00.000Z",
"last_attempt_at": null,
"last_success_at": null,
"last_observation_id": null,
"next_check_at": "2026-09-13T12:00:00.000Z",
"overdue_reason": null,
"id": "watch_example",
"source_url": "https://publisher.example.org/article",
"target_url": "https://example.com/",
"target_scope": "exact",
"expected_anchor": null,
"expected_rel": null,
"local_reference": "ledger:example",
"last_successful_observation_id": null,
"detail": "summary"
}
],
"next_cursor": null
}
```
## Response formats
`format` selects the row shape. `detailed` is the example above: every field. `concise` keeps, per row: `id`, `source_url`, `target_url`, `status`, `state`, `observation_state`, `next_check_at`, `local_reference`; 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 |
| ----------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cursor` | string | Optional | Opaque continuation returned by this same listing; omit for the first page. |
| `limit` | integer | Optional | Maximum rows in this page or bounded report; subject to the schema maximum. minimum: 1; maximum: 100; default: 50 |
| `projectId` | string | Optional | Identifier of the project returned by its create or list operation. minLength: 1; maxLength: 200 |
| `q` | string | Optional | Text filter applied to saved records; does not start discovery. maxLength: 500 |
| `state` | string | Optional | Requested resource state or saved-observation filter, as enumerated here. |
| `status` | string | Optional | Lifecycle status filter or requested status; this is separate from observation state. values: "active", "paused" |
| `include` | string | Optional | The include value; allowed values and bounds are specified in this schema. default: "summary"; values: "summary", "detail" |
| `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.
Omitting projectId reads the accessible workspace scope rather than selecting a different project.
Pages are ordered by creation time, then identifier, ascending.
Omitted q, state and status apply no corresponding filter. Search matches the source or target URL case-insensitively. include=detail returns the fuller record.
### Defaults when omitted
| Field | Default |
| --------- | ----------- |
| `limit` | `50` |
| `include` | `"summary"` |
## 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.
| Field | Type | Presence | Meaning and constraints |
| ---------------------------------------------------------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `items` | array | Required | Records in this bounded page. |
| `items[].id` | string | Required | Resource identifier returned by the operation. |
| `items[].workspace_id` | string | Required | Workspace that owns this record. |
| `items[].project_id` | string | Required | Project that owns this record. |
| `items[].status` | string | Required | Resource lifecycle status. values: "active", "paused" |
| `items[].cadence_seconds` | number | Required | |
| `items[].state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].observation_state` | object | Required | Saved observation state. Before the first check, this object can be empty. |
| `items[].observation_state.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].observation_state.uncertain` | boolean | Optional | |
| `items[].observation_state.checked_at` | string | Optional | UTC timestamp of the saved check. |
| `items[].observation_state.lastChangedAt` | string / null | Optional | |
| `items[].observation_state.firstAbsentAt` | string / null | Optional | |
| `items[].observation_state.consecutiveAbsent` | number | Optional | |
| `items[].observation_state.nextCheckAt` | string / null | Optional | |
| `items[].observation_state.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `items[].observation_state.latestAttempt` | object / null | Optional | |
| `items[].observation_state.latestAttempt.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].observation_state.latestAttempt.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `items[].observation_state.latestAttempt.checkedAt` | string | Optional | |
| `items[].observation_state.latestAttempt.httpStatus` | number / null | Optional | |
| `items[].observation_state.latestAttempt.occurrenceCount` | number | Optional | |
| `items[].observation_state.latestAttempt.occurrences` | array | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].href` | string / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].targetUrl` | string / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].anchor` | string / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].rel` | array | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].context` | string / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].locator` | object / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].locator.line` | number / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].locator.column` | number / null | Optional | |
| `items[].observation_state.latestAttempt.occurrences[].locator.offset` | number / null | Optional | |
| `items[].observation_state.latestAttempt.checkerVersion` | string | Optional | |
| `items[].observation_state.lastSuccessfulObservation` | object / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].observation_state.lastSuccessfulObservation.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `items[].observation_state.lastSuccessfulObservation.checkedAt` | string | Optional | |
| `items[].observation_state.lastSuccessfulObservation.httpStatus` | number / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrenceCount` | number | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences` | array | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].href` | string / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].targetUrl` | string / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].anchor` | string / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].rel` | array | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].context` | string / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].locator` | object / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].locator.line` | number / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].locator.column` | number / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.occurrences[].locator.offset` | number / null | Optional | |
| `items[].observation_state.lastSuccessfulObservation.checkerVersion` | string | Optional | |
| `items[].observation_state.lastSuccessfulObservationSameAsLatestAttempt` | boolean | Optional | |
| `items[].observation_state.confirmedState` | string / null | Optional | |
| `items[].observation_state.lastSuccessfulAt` | string / null | Optional | |
| `items[].observation_state.lastHealthyAt` | string / null | Optional | |
| `items[].observation_state.firstUnavailableAt` | string / null | Optional | |
| `items[].observation_state.unavailableCount` | number | Optional | |
| `items[].observation_state.wasEverHealthy` | boolean | Optional | |
| `items[].observation_state.retryNotBefore` | string / null | Optional | |
| `items[].observation_state.ignored` | boolean | Optional | |
| `items[].created_at` | string | Required | UTC timestamp when the record was created. |
| `items[].updated_at` | string | Required | UTC timestamp of the last record update. |
| `items[].last_attempt_at` | string / null | Required | |
| `items[].last_success_at` | string / null | Required | |
| `items[].last_observation_id` | string / null | Required | Identifier returned by the related operation. |
| `items[].next_check_at` | string / null | Required | |
| `items[].overdue_reason` | string / null | Required | |
| `items[].source_url` | string | Required | Publisher page URL recorded in this evidence. |
| `items[].target_url` | string | Required | Destination URL recorded in this evidence. |
| `items[].target_scope` | string | Required | |
| `items[].expected_anchor` | string / null | Required | |
| `items[].expected_rel` | array / null | Required | |
| `items[].local_reference` | string / null | Required | Customer reference for joining this record to a local ledger entry. |
| `items[].last_successful_observation_id` | string / null | Required | Identifier returned by the related operation. |
| `items[].history_compacted_before` | string / null | Optional | |
| `items[].created` | boolean | Optional | True when this request created the record; false when an existing record was reused. |
| `items[].detail` | string | Optional | |
| `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. |
[Download input schema](/schemas/list_link_watches.input.json) · [Download output schema](/schemas/list_link_watches.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/watches` | 200 | Remaining read arguments go in query parameters. |
## Continue
[get\_link\_watch](/reference/commands/get_link_watch)
Follow the [related workflow](/guides/monitor-changes), inspect [capability status](/capability-status), or return to the [command index](/reference/index).