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

# Common records and response conventions

> Understand shared identifiers, optional fields, pagination, jobs, observations, usage reservations and candidate batch results across the command reference.

Each [operation page](/mcp-tools/generated/overview) defines its exact input and output schema. The conventions here explain recurring fields. Use the operation's schema for validation: a watch, candidate, job and event do not share one universal response envelope.

## Inputs and identifiers

Send a JSON object using the documented field names and types. An optional field can be omitted; it accepts `null` only when its schema permits null. For supported expectation updates, null clears an expectation. Omission leaves that field outside the requested change.

Keep returned identifiers exactly as received. Use `projectId`, `watchId`, `runId`, `candidateId` or `jobId` in the operation that asks for it. A `localReference` associates a hosted record with a customer-owned record. Join through that reference rather than relying on identical URL spelling after normalization.

Reuse `idempotencyKey` only for retries of the same intended operation and arguments. Revision fields serve a different purpose: `expectedRevision` rejects stale concurrent updates, while a selected historical revision chooses immutable saved evidence.

## Records and pagination

| Shape             | Recurring fields                                               | Meaning                                                                    |
| ----------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------- |
| List page         | `items`, optional `next_cursor`                                | A bounded page of the selected records                                     |
| Event feed        | `events`, `next_cursor`, `has_more`                            | A feed page and its continuation position                                  |
| Source watch      | `id`, `source_url`, `target_url`, `state`, `observation_state` | A monitored placement with saved observation context                       |
| Destination watch | `id`, `url`, `state`, `observation_state`                      | Independent health evidence for one target URL                             |
| History item      | `id`, `state`, `checked_at`, `result`                          | One dated saved observation                                                |
| Check job         | `id`, `state`                                                  | Execution state: `queued`, `running`, `succeeded`, `failed` or `cancelled` |

Treat cursors as opaque. Follow the operation's continuation fields until its selected result set ends. Apply event pages before advancing the saved cursor. A cursor belongs to its feed and query; source and destination cursors cannot be exchanged.

## Evidence and missing values

Observation states `present`, `absent` and `unknown` describe link evidence. Destination states `healthy`, `unavailable` and `unknown` describe target health. A job can succeed while its observation remains unknown. Lifecycle `status`, such as `active` or `paused`, describes the watch rather than its last fetch.

Keep unknown and null values in reports. Missing supplier rows do not become zero links; missing search rows do not become zero impressions. Preserve the provider observation date, import/capture date and check date separately. [Evidence semantics](/evidence) defines confirmed loss and retained snapshots.

## Usage and batch results

[Usage](/reference/commands/get_usage) names the UTC `period`, unit totals and check reservations. Reserved, consumed and released totals describe different stages of work. Source and destination checks share allowance; discovery and overview counters describe separate work.

A [candidate verification batch](/reference/commands/get_candidate_verification_batch) has `schema_version: 1`, aggregate state and counts, per-item results and a reservation. Each item can have a nullable job, watch, observation, error and usage record. Read all items: a partial batch includes outcomes that need different next actions. The batch's `completed` state alone does not establish link presence.

Response contracts permit extension fields where documented so clients can retain new information. Validate known required fields without silently inventing defaults for absent evidence. See [error conventions](/reference/errors), [concepts](/guides/concepts) and [sync recovery](/guides/sync-and-export) before building a consumer.

The [local context result reference](/reference/context/results) describes the separate stdio result envelope and per-tool records.