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

# Read saved profile records

> Read exact saved watch rows behind a profile chart, optionally filtered by saved or assessed category, with paginated JSON or spreadsheet-safe CSV.

`list_profile_snapshot_records`

Read exact saved watch rows behind a profile chart, optionally filtered by saved or assessed category, with paginated JSON or spreadsheet-safe CSV. CSV additionally requires exports:create. No new collection.

<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_snapshot_records",
      "arguments": {
        "projectId": "project_example",
        "snapshotId": "snapshot_example",
        "limit": 100,
        "format": "json"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call list_profile_snapshot_records --args '{"projectId":"project_example","snapshotId":"snapshot_example","limit":100,"format":"json"}'
  ```

  ```bash HTTP theme={null}
  curl --fail-with-body https://app.agentlinkops.com/v1/commands/list_profile_snapshot_records \
    -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data '{"projectId":"project_example","snapshotId":"snapshot_example","limit":100,"format":"json"}'
  ```
</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}
  {
    "snapshot": {
      "schema_version": 1,
      "id": "snapshot_example",
      "workspace_id": "workspace_example",
      "project_id": "project_example",
      "capture_started_at": "2026-10-14T12:00:00.000Z",
      "captured_at": "2026-10-14T12:00:00.000Z",
      "expires_at": "2027-01-12T12:00:00.000Z",
      "content_hash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "basis": "non_archived_monitored_watches",
      "consistency": "bounded_read_interval",
      "unique_physical_links": false,
      "whole_web_coverage": false,
      "total_watches": 0,
      "categories": {
        "display": {
          "denominator": 0,
          "known_count": 0,
          "unknown_count": 0,
          "unknown_share": null,
          "items": []
        },
        "chosen": {
          "denominator": 0,
          "known_count": 0,
          "unknown_count": 0,
          "unknown_share": null,
          "items": []
        },
        "assessed": {
          "denominator": 0,
          "known_count": 0,
          "unknown_count": 0,
          "unknown_share": null,
          "items": []
        }
      },
      "authority": [],
      "notes": [
        "This empty example does not establish that no links existed."
      ]
    },
    "total_records": 0,
    "items": [],
    "next_cursor": null,
    "has_more": false,
    "format": "json",
    "csv": null
  }
  ```
</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` |
| `snapshotId` | string | Required | snapshot ID from create/list. minLength: `1`; maxLength: `200` |
| `cursor` | integer | Optional | Opaque list cursor; omit initially. minimum: `0`; maximum: `9007199254740991`; default: `0` |
| `limit` | integer | Optional | Page/report row cap; see bounds. minimum: `1`; maximum: `200`; default: `100` |
| `categoryBasis` | string | Optional | category basis; see schema. default: `"display"`; values: `"display"`, `"chosen"`, `"assessed"` |
| `category` | string / null | Optional | category; see schema. |
| `format` | string | Optional | format; see schema. default: `"json"`; values: `"json"`, `"csv"` |

### Validation and omitted values

Requires watches:read; CSV also requires exports:create. Read the exact snapshotId and projectId returned by a save or list. Records use ascending ordinal order, with at most 200 rows per page. Continue with next\_cursor while has\_more is true.

Omitting category returns all saved records. Supplying category=null selects unknown category values; supplying a string selects that exact saved value. categoryBasis selects display, chosen or assessed and only affects a supplied category filter. Keep the snapshot and filters unchanged across pages.

total\_records counts the selected records. CSV contains only this page, with a header and spreadsheet-safe escaping. Assemble every page before claiming a complete export.

An expired, erased or incomplete snapshot is unavailable. Save a new baseline if needed; its current values cannot replace the missing historical snapshot.

### Defaults when omitted

| Field | Default |
| - | - |
| `limit` | `100` |
| `cursor` | `0` |
| `categoryBasis` | `"display"` |
| `format` | `"json"` |

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

* **`snapshot`** (object, required): additional fields rejected
* **`total_records`** (integer, required): minimum: `0`; maximum: `9007199254740991`
* **`items`** (array, required): Records in this bounded page.
* **`next_cursor`** (integer / null, required): Opaque continuation for the same listing; null means no further page.
* **`has_more`** (boolean, required): True when another page is available.
* **`format`** (string, required): values: `"json"`, `"csv"`
* **`csv`** (string / null, required).

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `snapshot` | object | Required | additional fields rejected |
  | `snapshot.schema_version` | number | Required | must equal `1` |
  | `snapshot.id` | string | Required | Resource identifier returned by the operation. minLength: `1`; maxLength: `200` |
  | `snapshot.workspace_id` | string | Required | Workspace that owns this record. minLength: `1`; maxLength: `200` |
  | `snapshot.project_id` | string | Required | Project that owns this record. minLength: `1`; maxLength: `200` |
  | `snapshot.capture_started_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshot.captured_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshot.expires_at` | string | Required | pattern: `"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"` |
  | `snapshot.content_hash` | string | Required | pattern: `"^sha256:[a-f0-9]{64}$"` |
  | `snapshot.basis` | string | Required | must equal `"non_archived_monitored_watches"` |
  | `snapshot.consistency` | string | Required | must equal `"bounded_read_interval"` |
  | `snapshot.unique_physical_links` | boolean | Required | must equal `false` |
  | `snapshot.whole_web_coverage` | boolean | Required | False: these results do not measure the whole web. must equal `false` |
  | `snapshot.total_watches` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories` | object | Required | additional fields rejected |
  | `snapshot.categories.display` | object | Required | additional fields rejected |
  | `snapshot.categories.display.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.display.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.display.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.display.unknown_share` | number / null | Required | |
  | `snapshot.categories.display.items` | array | Required | Records in this bounded page. |
  | `snapshot.categories.display.items[].value` | string / null | Required | |
  | `snapshot.categories.display.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.display.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshot.categories.chosen` | object | Required | additional fields rejected |
  | `snapshot.categories.chosen.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.chosen.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.chosen.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.chosen.unknown_share` | number / null | Required | |
  | `snapshot.categories.chosen.items` | array | Required | Records in this bounded page. |
  | `snapshot.categories.chosen.items[].value` | string / null | Required | |
  | `snapshot.categories.chosen.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.chosen.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshot.categories.assessed` | object | Required | additional fields rejected |
  | `snapshot.categories.assessed.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.assessed.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.assessed.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.assessed.unknown_share` | number / null | Required | |
  | `snapshot.categories.assessed.items` | array | Required | Records in this bounded page. |
  | `snapshot.categories.assessed.items[].value` | string / null | Required | |
  | `snapshot.categories.assessed.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.categories.assessed.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshot.authority` | array | Required | |
  | `snapshot.authority[].provider` | string | Required | |
  | `snapshot.authority[].name` | string | Required | |
  | `snapshot.authority[].scope` | string | Required | values: `"page"`, `"domain"` |
  | `snapshot.authority[].scale` | string | Required | |
  | `snapshot.authority[].histogram` | object | Required | additional fields rejected |
  | `snapshot.authority[].histogram.denominator` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.authority[].histogram.known_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.authority[].histogram.unknown_count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.authority[].histogram.unknown_share` | number / null | Required | |
  | `snapshot.authority[].histogram.items` | array | Required | Records in this bounded page. |
  | `snapshot.authority[].histogram.items[].value` | string / null | Required | |
  | `snapshot.authority[].histogram.items[].count` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `snapshot.authority[].histogram.items[].share` | number | Required | minimum: `0`; maximum: `1` |
  | `snapshot.authority[].mean` | number / null | Required | |
  | `snapshot.authority[].oldest_retrieved_at` | string / null | Required | |
  | `snapshot.authority[].newest_retrieved_at` | string / null | Required | |
  | `snapshot.notes` | array | Required | |
  | `total_records` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items` | array | Required | Records in this bounded page. |
  | `items[].ordinal` | integer | Required | minimum: `0`; maximum: `9007199254740991` |
  | `items[].watch_id` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
  | `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[].status` | string | Required | Resource lifecycle status. |
  | `items[].state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
  | `items[].last_observation_id` | string / null | Required | Identifier returned by the related operation. |
  | `items[].category_contract` | string | Required | must equal `"link-category-v1"` |
  | `items[].chosen_category` | object | Required | |
  | `items[].page_assessment` | object | Required | |
  | `items[].display_category` | object | Required | |
  | `items[].category_values` | object | Required | additional fields rejected |
  | `items[].category_values.display` | string / null | Required | |
  | `items[].category_values.chosen` | string / null | Required | |
  | `items[].category_values.assessed` | string / null | Required | |
  | `items[].authority` | array | Required | |
  | `items[].authority[].provider` | string | Required | must equal `"dataforseo"` |
  | `items[].authority[].name` | string | Required | must equal `"rank"` |
  | `items[].authority[].scale` | string | Required | must equal `"0-1000"` |
  | `items[].authority[].scope` | string | Required | values: `"page"`, `"domain"` |
  | `items[].authority[].target` | string | Required | |
  | `items[].authority[].value` | integer / null | Required | |
  | `items[].authority[].retrievedAt` | string | Required | |
  | `items[].authority[].supplierObservedAt` | string / null | Required | |
  | `items[].authority[].provenance` | string | Optional | must equal `"imported"` |
  | `next_cursor` | integer / null | Required | Opaque continuation for the same listing; null means no further page. |
  | `has_more` | boolean | Required | True when another page is available. |
  | `format` | string | Required | values: `"json"`, `"csv"` |
  | `csv` | string / null | Required | |
</Accordion>

[Download input schema](/schemas/list_profile_snapshot_records.input.json) · [Download output schema](/schemas/list_profile_snapshot_records.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`, `PROFILE_SNAPSHOT_UNAVAILABLE`, `INSUFFICIENT_SCOPE`.

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

[list\_profile\_snapshots](/reference/commands/list_profile_snapshots) · [save\_profile\_snapshot](/reference/commands/save_profile_snapshot)

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.