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

# Compare saved link profiles

> Read retained saved category and native-rank history for selected websites, or deterministic latest-per-site profiles.

`list_profile_snapshots`

Read retained saved category and native-rank history for selected websites, or deterministic latest-per-site profiles. History begins at the first explicit save, not at the first discovered link.

<Note>This command name is absent from deployment evidence dated 2026-09-20. Hosted availability for this current definition is unverified; inspect your connected catalog before invoking it. Verify the command and its input schema in the selected environment.</Note>

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

<CodeGroup>
  ```json MCP theme={null}
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_profile_snapshots",
      "arguments": {
        "projectIds": [
          "project_example"
        ],
        "limit": 50
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call list_profile_snapshots --args '{"projectIds":["project_example"],"limit":50}'
  ```

  ```bash HTTP theme={null}
  curl --fail-with-body https://app.agentlinkops.com/v1/commands/list_profile_snapshots \
    -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data '{"projectIds":["project_example"],"limit":50}'
  ```
</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}
{
  "schema_version": 1,
  "snapshots": [],
  "has_more": false,
  "next_cursor": null,
  "selection_mode": "history",
  "missing_project_ids": [],
  "comparison_basis": "separate_saved_watch_populations",
  "notes": []
}
```

## 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 |
| - | - | - | - |
| `projectIds` | array | Required | Accessible project IDs. Where nullable, null grants all projects. minItems: `1`; maxItems: `10` |
| `from` | string | Optional | from; see schema. pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
| `to` | string | Optional | to; see schema. pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
| `limit` | integer | Optional | Page/report row cap; see bounds. minimum: `1`; maximum: `100`; default: `50` |
| `cursor` | string | Optional | Opaque list cursor; omit initially. maxLength: `4096` |
| `latestPerProject` | boolean | Optional | latest per project; see schema. default: `false` |

### Validation and omitted values

Supply one to ten distinct accessible projectIds. Omitted from and to impose no date filter beyond retention; supplied bounds apply to capture time inclusively. Expired snapshots are excluded.

History mode orders snapshots by captured\_at and identifier, newest first. Keep projectIds and date bounds unchanged when continuing with next\_cursor. The maximum history page size is 100.

latestPerProject=true returns one latest retained snapshot per selected project within the date bounds, ordered by project identifier. This mode ignores limit, does not paginate and rejects a supplied continuation cursor. missing\_project\_ids names sites without a retained snapshot in that interval.

Each site keeps its own saved date and watch denominator. Missing snapshots do not mean zero links. Compare the separate saved populations without pooling them or backfilling earlier dates.

### Defaults when omitted

| Field | Default |
| - | - |
| `limit` | `50` |
| `latestPerProject` | `false` |

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

* **`schema_version`** (number, required): must equal `1`
* **`snapshots`** (array, required).
* **`has_more`** (boolean, required): True when another page is available.
* **`next_cursor`** (string / null, required): Opaque continuation for the same listing; null means no further page.
* **`selection_mode`** (string, required): values: `"history"`, `"latest_per_project"`
* **`missing_project_ids`** (array, required).
* **`comparison_basis`** (string, required): must equal `"separate_saved_watch_populations"`
* **`notes`** (array, required).

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `schema_version` | number | Required | must equal `1` |
  | `snapshots` | array | Required | |
  | `snapshots[].schema_version` | number | Required | must equal `1` |
  | `snapshots[].id` | string | Required | Resource identifier returned by the operation. minLength: `1`; maxLength: `200` |
  | `snapshots[].workspace_id` | string | Required | Workspace that owns this record. minLength: `1`; maxLength: `200` |
  | `snapshots[].project_id` | string | Required | Project that owns this record. minLength: `1`; maxLength: `200` |
  | `snapshots[].capture_started_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshots[].captured_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshots[].expires_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshots[].content_hash` | string | Required | pattern: `"^sha256:[a-f0-9]{64}$"` |
  | `snapshots[].basis` | string | Required | must equal `"non_archived_monitored_watches"` |
  | `snapshots[].consistency` | string | Required | must equal `"bounded_read_interval"` |
  | `snapshots[].unique_physical_links` | boolean | Required | must equal `false` |
  | `snapshots[].whole_web_coverage` | boolean | Required | False: these results do not measure the whole web. must equal `false` |
  | `snapshots[].total_watches` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories` | object | Required | additional fields rejected |
  | `snapshots[].categories.display` | object | Required | additional fields rejected |
  | `snapshots[].categories.display.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.display.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.display.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.display.unknown_share` | number / null | Required | |
  | `snapshots[].categories.display.items` | array | Required | Records in this bounded page. |
  | `snapshots[].categories.display.items[].value` | string / null | Required | |
  | `snapshots[].categories.display.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.display.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshots[].categories.chosen` | object | Required | additional fields rejected |
  | `snapshots[].categories.chosen.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.chosen.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.chosen.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.chosen.unknown_share` | number / null | Required | |
  | `snapshots[].categories.chosen.items` | array | Required | Records in this bounded page. |
  | `snapshots[].categories.chosen.items[].value` | string / null | Required | |
  | `snapshots[].categories.chosen.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.chosen.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshots[].categories.assessed` | object | Required | additional fields rejected |
  | `snapshots[].categories.assessed.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.assessed.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.assessed.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.assessed.unknown_share` | number / null | Required | |
  | `snapshots[].categories.assessed.items` | array | Required | Records in this bounded page. |
  | `snapshots[].categories.assessed.items[].value` | string / null | Required | |
  | `snapshots[].categories.assessed.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].categories.assessed.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshots[].authority` | array | Required | |
  | `snapshots[].authority[].provider` | string | Required | |
  | `snapshots[].authority[].name` | string | Required | |
  | `snapshots[].authority[].scope` | string | Required | values: `"page"`, `"domain"` |
  | `snapshots[].authority[].scale` | string | Required | |
  | `snapshots[].authority[].histogram` | object | Required | additional fields rejected |
  | `snapshots[].authority[].histogram.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].authority[].histogram.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].authority[].histogram.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].authority[].histogram.unknown_share` | number / null | Required | |
  | `snapshots[].authority[].histogram.items` | array | Required | Records in this bounded page. |
  | `snapshots[].authority[].histogram.items[].value` | string / null | Required | |
  | `snapshots[].authority[].histogram.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshots[].authority[].histogram.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshots[].authority[].mean` | number / null | Required | |
  | `snapshots[].authority[].oldest_retrieved_at` | string / null | Required | |
  | `snapshots[].authority[].newest_retrieved_at` | string / null | Required | |
  | `snapshots[].notes` | array | Required | |
  | `has_more` | boolean | Required | True when another page is available. |
  | `next_cursor` | string / null | Required | Opaque continuation for the same listing; null means no further page. |
  | `selection_mode` | string | Required | values: `"history"`, `"latest_per_project"` |
  | `missing_project_ids` | array | Required | |
  | `comparison_basis` | string | Required | must equal `"separate_saved_watch_populations"` |
  | `notes` | array | Required | |
</Accordion>

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

## Errors and retries

Follow the error recovery before retrying this read. Preserve the selected workspace, project, filters and feed. Recovering a read does not require an idempotency key or another verification job. Operation-specific errors include `INVALID_PROFILE_SNAPSHOT_INPUT`, `PROFILE_SNAPSHOT_ACCESS_DENIED`, `PROFILE_SNAPSHOT_SCHEMA_UNAVAILABLE`, `INVALID_PROFILE_SNAPSHOT_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

This operation has no separate resource alias. Use its generic command route in a matching environment.

## Continue

[save\_profile\_snapshot](/reference/commands/save_profile_snapshot) · [list\_profile\_snapshot\_records](/reference/commands/list_profile_snapshot_records)

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