> ## 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.
# Monitor link
> Monitor a known source page and target.
`monitor_link`
Monitor a known source page and target. Identical placements are deduplicated. Source URLs are stored normalized; join local records using local\_reference rather than raw URL strings.
Hosted MCP registration verified. These schemas describe the development contract; confirm supported inputs with tools/list. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.
| Access | Behavior |
| --------------- | --------------------- |
| `watches:write` | Writes or admits work |
Checks and monitoring can consume workspace capacity. Queued admission is not a completed observation; inspect the returned job or saved state.
## 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": "monitor_link",
"arguments": {
"projectId": "project_example",
"sourceUrl": "https://publisher.example.com/resources",
"targetUrl": "https://example.com/guide"
}
}
}
```
```bash CLI theme={null}
linktrail call monitor_link --args '{"projectId":"project_example","sourceUrl":"https://publisher.example.com/resources","targetUrl":"https://example.com/guide"}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/monitor_link" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"projectId":"project_example","sourceUrl":"https://publisher.example.com/resources","targetUrl":"https://example.com/guide"}'
```
## 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}
{
"workspace_id": "ws_example",
"project_id": "project_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.com/resources",
"target_url": "https://example.com/guide",
"target_scope": "exact",
"expected_anchor": null,
"expected_rel": null,
"local_reference": null,
"last_successful_observation_id": null,
"created": true
}
```
## 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 | Identifier of the project returned by its create or list operation. minLength: 1; maxLength: 200 |
| `sourceUrl` | string | Required | Public publisher page URL containing the placement to inspect. format: "uri" |
| `targetUrl` | string | Required | Public destination URL expected in the placement. format: "uri" |
| `targetScope` | string | Optional | URL matching rule: exact URL, domain, subdomain, or path prefix. default: "exact"; values: "exact", "domain", "subdomain", "path" |
| `cadenceSeconds` | integer | Optional | Scheduled check interval in seconds, from 3600 to 2592000. minimum: 3600; maximum: 2592000; default: 86400 |
| `expectedAnchor` | string / null | Optional | Expected link anchor text; null clears the expectation. default: null |
| `expectedRel` | array / null | Optional | Expected rel tokens; null clears the expectation. default: null |
| `localReference` | string | Optional | Customer-owned reference to associate this record with a local ledger entry. maxLength: 200 |
### Validation and omitted values
Omitted expectedAnchor, expectedRel and localReference are stored without an expectation or local reference. Identical normalized source/target/scope records in the same project return the existing watch without replacing its settings.
Relation expectations allow at most twenty tokens; each token uses one to forty letters, digits, `_` or `-`. Tokens are normalized to lowercase, deduplicated and sorted.
A new watch is due immediately. This operation enrolls monitoring; read a completed check before claiming presence.
### Defaults when omitted
| Field | Default |
| ---------------- | --------- |
| `targetScope` | `"exact"` |
| `cadenceSeconds` | `86400` |
| `expectedAnchor` | `null` |
| `expectedRel` | `null` |
## 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.
| Field | Type | Presence | Meaning and constraints |
| -------------------------------------------------------------------------- | ------------- | -------- | ------------------------------------------------------------------------------------ |
| `id` | string | Required | Resource identifier returned by the operation. |
| `workspace_id` | string | Required | Workspace that owns this record. |
| `project_id` | string | Required | Project that owns this record. |
| `status` | string | Required | Resource lifecycle status. values: "active", "paused" |
| `cadence_seconds` | number | Required | cadence seconds recorded for this result. |
| `state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `observation_state` | object | Required | Saved observation state. Before the first check, this object can be empty. |
| `observation_state.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `observation_state.uncertain` | boolean | Optional | uncertain recorded for this result. |
| `observation_state.checked_at` | string | Optional | UTC timestamp of the saved check. |
| `observation_state.lastChangedAt` | string / null | Optional | last Changed At recorded for this result. |
| `observation_state.firstAbsentAt` | string / null | Optional | first Absent At recorded for this result. |
| `observation_state.consecutiveAbsent` | number | Optional | consecutive Absent recorded for this result. |
| `observation_state.nextCheckAt` | string / null | Optional | next Check At recorded for this result. |
| `observation_state.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `observation_state.latestAttempt` | object / null | Optional | latest Attempt recorded for this result. |
| `observation_state.latestAttempt.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `observation_state.latestAttempt.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `observation_state.latestAttempt.checkedAt` | string | Optional | checked At recorded for this result. |
| `observation_state.latestAttempt.httpStatus` | number / null | Optional | http Status recorded for this result. |
| `observation_state.latestAttempt.occurrenceCount` | number | Optional | occurrence Count recorded for this result. |
| `observation_state.latestAttempt.occurrences` | array | Optional | occurrences recorded for this result. |
| `observation_state.latestAttempt.occurrences[].href` | string / null | Optional | href recorded for this result. |
| `observation_state.latestAttempt.occurrences[].targetUrl` | string / null | Optional | target Url recorded for this result. |
| `observation_state.latestAttempt.occurrences[].anchor` | string / null | Optional | anchor recorded for this result. |
| `observation_state.latestAttempt.occurrences[].rel` | array | Optional | rel recorded for this result. |
| `observation_state.latestAttempt.occurrences[].context` | string / null | Optional | context recorded for this result. |
| `observation_state.latestAttempt.occurrences[].locator` | object / null | Optional | locator recorded for this result. |
| `observation_state.latestAttempt.occurrences[].locator.line` | number / null | Optional | line recorded for this result. |
| `observation_state.latestAttempt.occurrences[].locator.column` | number / null | Optional | column recorded for this result. |
| `observation_state.latestAttempt.occurrences[].locator.offset` | number / null | Optional | offset recorded for this result. |
| `observation_state.latestAttempt.checkerVersion` | string | Optional | checker Version recorded for this result. |
| `observation_state.lastSuccessfulObservation` | object / null | Optional | last Successful Observation recorded for this result. |
| `observation_state.lastSuccessfulObservation.state` | string | Optional | Saved lifecycle or evidence state, as enumerated for this record. |
| `observation_state.lastSuccessfulObservation.reason` | string / null | Optional | Recorded explanation; null when no explanation applies. |
| `observation_state.lastSuccessfulObservation.checkedAt` | string | Optional | checked At recorded for this result. |
| `observation_state.lastSuccessfulObservation.httpStatus` | number / null | Optional | http Status recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrenceCount` | number | Optional | occurrence Count recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences` | array | Optional | occurrences recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].href` | string / null | Optional | href recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].targetUrl` | string / null | Optional | target Url recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].anchor` | string / null | Optional | anchor recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].rel` | array | Optional | rel recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].context` | string / null | Optional | context recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].locator` | object / null | Optional | locator recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].locator.line` | number / null | Optional | line recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].locator.column` | number / null | Optional | column recorded for this result. |
| `observation_state.lastSuccessfulObservation.occurrences[].locator.offset` | number / null | Optional | offset recorded for this result. |
| `observation_state.lastSuccessfulObservation.checkerVersion` | string | Optional | checker Version recorded for this result. |
| `observation_state.lastSuccessfulObservationSameAsLatestAttempt` | boolean | Optional | last Successful Observation Same As Latest Attempt recorded for this result. |
| `observation_state.confirmedState` | string / null | Optional | confirmed State recorded for this result. |
| `observation_state.lastSuccessfulAt` | string / null | Optional | last Successful At recorded for this result. |
| `observation_state.lastHealthyAt` | string / null | Optional | last Healthy At recorded for this result. |
| `observation_state.firstUnavailableAt` | string / null | Optional | first Unavailable At recorded for this result. |
| `observation_state.unavailableCount` | number | Optional | unavailable Count recorded for this result. |
| `observation_state.wasEverHealthy` | boolean | Optional | was Ever Healthy recorded for this result. |
| `observation_state.retryNotBefore` | string / null | Optional | retry Not Before recorded for this result. |
| `observation_state.ignored` | boolean | Optional | ignored recorded for this result. |
| `created_at` | string | Required | UTC timestamp when the record was created. |
| `updated_at` | string | Required | UTC timestamp of the last record update. |
| `last_attempt_at` | string / null | Required | last attempt at recorded for this result. |
| `last_success_at` | string / null | Required | last success at recorded for this result. |
| `last_observation_id` | string / null | Required | last observation id recorded for this result. |
| `next_check_at` | string / null | Required | next check at recorded for this result. |
| `overdue_reason` | string / null | Required | overdue reason recorded for this result. |
| `source_url` | string | Required | Publisher page URL recorded in this evidence. |
| `target_url` | string | Required | Destination URL recorded in this evidence. |
| `target_scope` | string | Required | target scope recorded for this result. |
| `expected_anchor` | string / null | Required | expected anchor recorded for this result. |
| `expected_rel` | array / null | Required | expected rel recorded for this result. |
| `local_reference` | string / null | Required | Customer reference for joining this record to a local ledger entry. |
| `last_successful_observation_id` | string / null | Required | last successful observation id recorded for this result. |
| `history_compacted_before` | string / null | Optional | history compacted before recorded for this result. |
| `created` | boolean | Optional | True when this request created the record; false when an existing record was reused. |
| `detail` | string | Optional | detail recorded for this result. |
[Download input schema](/schemas/monitor_link.input.json) · [Download output schema](/schemas/monitor_link.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
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/watches` | 201 | Remaining arguments go in a JSON object body. |
## Continue
[request\_link\_check](/reference/commands/request_link_check) · [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).