> ## 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 backlink contacts

> Read private backlink contacts for one project.

`list_contacts`

Read private backlink contacts for one project. Optional watchId returns its saved association; after continues the same filters.

> [!NOTE]
>
> Name recorded in the 2026-10-27 deployment. This page describes current source; verify inputs and access in your connected catalog. Provider configuration and workspace access still apply.

| Access | Behavior |
| - | - |
| `watches:read` | Reads saved data |

## Example request

Connect through [MCP](https://docs.agentlinkops.com/guides/connect-mcp.md), [CLI](https://docs.agentlinkops.com/guides/connect-cli.md), or [HTTP](https://docs.agentlinkops.com/guides/connect-http.md). Replace example identifiers with records from your workspace.

```json MCP theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_contacts",
    "arguments": {
      "projectId": "project_example",
      "watchId": "watch_example",
      "limit": 50
    }
  }
}
```

```bash CLI theme={null}
agentlinkops call list_contacts --args '{"projectId":"project_example","watchId":"watch_example","limit":50}'
```

```bash HTTP theme={null}
curl --fail-with-body https://app.agentlinkops.com/v1/commands/list_contacts \
  -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"projectId":"project_example","watchId":"watch_example","limit":50}'
```

## Returned result

Schema-validated example; IDs and dates are illustrative. 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": [
    {
      "id": "contact_example",
      "projectId": "pr_example",
      "externalRef": "outreach:example:publisher",
      "name": "Example publisher",
      "email": "editor@publisher.example",
      "contactUrl": null,
      "revision": "e61fed8c-85c3-4f30-a4d8-d84934f27698",
      "createdAt": "2026-09-13T12:00:00.000Z",
      "updatedAt": "2026-09-13T12:00:00.000Z"
    }
  ],
  "nextAfter": null,
  "link": {
    "watchId": "watch_example",
    "contactId": "contact_example",
    "revision": "e61fed8c-85c3-4f30-a4d8-d84934f27698"
  }
}
```

## 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` |
| `externalRef` | string | Optional | minLength: `1`; maxLength: `200` |
| `contactId` | string | Optional | contact ID from create/list. minLength: `1`; maxLength: `200` |
| `watchId` | string | Optional | watch ID from create/list. minLength: `1`; maxLength: `200` |
| `after` | string | Optional | minLength: `1`; maxLength: `200` |
| `limit` | integer | Required | Page/report row cap; see bounds. minimum: `1`; maximum: `100`; default: `50` |

### Validation and omitted values

Reads private contacts within one project. A watchId also returns its selected contact and association revision. The page cursor keeps the same filters.

Contact storage requires a separate capability and migration. Customer catalogs omit these commands while the capability is off.

### Defaults when omitted

| Field | Default |
| - | - |
| `limit` | `50` |

## Output fields

Fields inside optional or nullable parents apply only when that parent exists. [Common schema conventions](https://docs.agentlinkops.com/reference/schemas.md) explain evidence states, empty lists and extensions.

* **`items`** (array, required): Records in this bounded page.
* **`nextAfter`** (string / null, required).
* **`link`** (object / null, required).
* **`terms`** (object, optional).

> **All fields and nested objects**
>
> Types, allowed values, limits and nested fields:
>
> | Field | Type | Presence | Meaning and constraints |
> | - | - | - | - |
> | `items` | array | Required | Records in this bounded page. |
> | `items[].externalRef` | string | Required | minLength: `1`; maxLength: `200` |
> | `items[].name` | string | Required | minLength: `1`; maxLength: `120` |
> | `items[].email` | string / null | Required | |
> | `items[].contactUrl` | string / null | Required | |
> | `items[].id` | string | Required | Resource identifier returned by the operation. minLength: `1`; maxLength: `200` |
> | `items[].projectId` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
> | `items[].revision` | string | Required | Revision of this saved contact. Supply it as revision when updating or deleting the contact. format: `"uuid"`; pattern: `"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\|00000000-0000-0000-0000-000000000000\|ffffffff-ffff-ffff-ffff-ffffffffffff)$"` |
> | `items[].createdAt` | string | Required | |
> | `items[].updatedAt` | string | Required | |
> | `items[].attention` | object / null | Optional | |
> | `items[].relatedRecords` | array | Optional | |
> | `items[].relatedRecords[].watchId` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
> | `items[].relatedRecords[].sourceUrl` | string / null | Required | |
> | `items[].relatedRecords[].publisherUrl` | string | Required | |
> | `items[].relatedRecords[].targetUrl` | string | Required | |
> | `items[].relatedRecords[].progress` | string / null | Required | |
> | `items[].relatedRecords[].monitoring` | boolean | Required | |
> | `items[].relatedRecords[].participationId` | string | Optional | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
> | `items[].relatedRecords[].campaign` | string | Optional | |
> | `items[].relatedRecords[].lastContactedAt` | string / null | Optional | |
> | `items[].hasMoreRelatedRecords` | boolean | Optional | |
> | `nextAfter` | string / null | Required | |
> | `link` | object / null | Required | |
> | `link.watchId` | string | Required | Identifier returned by the related operation. minLength: `1`; maxLength: `200` |
> | `link.contactId` | string / null | Required | Identifier returned by the related operation. |
> | `link.revision` | number / string | Required | Current association revision from list\_contacts; 0 creates the first association. |
> | `terms` | object | Optional | additional fields rejected |
> | `terms.version` | string | Required | |
> | `terms.accepted` | boolean | Required | |
> | `terms.canAcknowledge` | boolean | Required | |
> | `terms.ready` | boolean | Required | |
> | `terms.url` | string | Required | must equal `"https://agentlinkops.com/terms/#your-data"` |

[Download input schema](https://docs.agentlinkops.com/schemas/list_contacts.input.json) · [Download output schema](https://docs.agentlinkops.com/schemas/list_contacts.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.

See [error recovery](https://docs.agentlinkops.com/reference/errors.md) 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\_contact](https://docs.agentlinkops.com/reference/commands/save_contact.md) · [set\_link\_contact](https://docs.agentlinkops.com/reference/commands/set_link_contact.md)

Follow the [related workflow](https://docs.agentlinkops.com/guides/monitor-changes.md). See [capability status](https://docs.agentlinkops.com/capability-status.md) for availability or the [command index](https://docs.agentlinkops.com/reference/index.md) for another operation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.