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

# Choose a saved competitor analysis

> List competitor analyses.

`list_competitor_analyses`

List competitor analyses. Return retained references for a current approved competitor member. Open an ID for progress. Listing does not fetch pages, buy supplier data or start monitoring.

<Note>This command name appears in deployment evidence dated 2026-10-17. This page describes current source; read your connected catalog for deployed inputs and access. Workspace scopes and enabled providers still apply.</Note>

| Access | Behavior |
| - | - |
| `discovery: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_competitor_analyses",
      "arguments": {
        "projectId": "prj_example",
        "setId": "cs_example",
        "revision": 1,
        "memberId": "cm_example",
        "limit": 25
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call list_competitor_analyses --args '{"projectId":"prj_example","setId":"cs_example","revision":1,"memberId":"cm_example","limit":25}'
  ```

  ```bash HTTP theme={null}
  curl --fail-with-body https://app.agentlinkops.com/v1/commands/list_competitor_analyses \
    -H "Authorization: Bearer $AGENTLINKOPS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data '{"projectId":"prj_example","setId":"cs_example","revision":1,"memberId":"cm_example","limit":25}'
  ```
</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}
  {
    "schema_version": 1,
    "workspace_id": "ws_example",
    "project_id": "prj_example",
    "competitor_binding": {
      "setId": "cs_example",
      "revision": 1,
      "memberId": "cm_example"
    },
    "scope": {
      "domain": "rival.example.org",
      "include_subdomains": true
    },
    "items": [
      {
        "id": "ca_example",
        "created_at": "2026-10-15T12:00:00.000Z",
        "expires_at": "2026-11-14T12:00:00.000Z"
      }
    ],
    "next_cursor": null,
    "has_more": false,
    "page": {
      "limit": 25,
      "sort": "created_at",
      "order": "desc",
      "total": null,
      "query_scope": "server_dataset",
      "nulls": "last"
    }
  }
  ```
</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. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
| `setId` | string | Required | set ID from create/list. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
| `revision` | integer | Required | Revision of the approved competitor set bound to this offer or run. Pass the current set revision as revision when preparing an offer. maximum: `9007199254740991`; exclusiveMinimum: `0` |
| `memberId` | string | Required | member ID from create/list. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
| `limit` | integer | Optional | Page/report row cap; see bounds. minimum: `1`; maximum: `100`; default: `25` |
| `cursor` | string | Optional | Opaque list cursor; omit initially. minLength: `1`; maxLength: `16384` |

### Validation and omitted values

Requires the exact current approved set revision and competitor member under the selected project. Retired sets, replaced selections and customer-role members cannot be listed.

Returns retained IDs and their original created\_at and expires\_at timestamps, newest creation first with descending ID ties. It does not infer analysis state or update retention; read a selected ID for saved progress.

Earlier analyses retain their original 30-day creation window. Paginated analyses require their retained retrieval checkpoint, original expiry and current website scope and revision. Expired analyses and analyses whose paginated retrieval checkpoint was erased are omitted.

limit defaults to 25 with a maximum of 100. Totals are not computed: page.total is null. Omit cursor for the first page. Keep cursors opaque and continue only with the same project, approved binding, scope and credential permissions. Every page rechecks current authority and retention.

Listing is effect-free: no page fetch, supplier purchase, job dispatch, retry, lease renewal or recurring monitor is created.

### Defaults when omitted

| Field | Default |
| - | - |
| `limit` | `25` |

## 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`
* **`workspace_id`** (string, required): Workspace that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"`
* **`project_id`** (string, required): Project that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"`
* **`competitor_binding`** (object, required): additional fields rejected
* **`scope`** (object, required): additional fields rejected
* **`items`** (array, required): Records in this bounded page. maxItems: `100`
* **`next_cursor`** (string / null, required): Opaque continuation for the same listing; null means no further page.
* **`has_more`** (boolean, required): True when another page is available.
* **`page`** (object, required): additional fields rejected

<Accordion title="All fields and nested objects">
  | Field | Type | Presence | Meaning and constraints |
  | - | - | - | - |
  | `schema_version` | number | Required | must equal `1` |
  | `workspace_id` | string | Required | Workspace that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `project_id` | string | Required | Project that owns this record. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `competitor_binding` | object | Required | additional fields rejected |
  | `competitor_binding.setId` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `competitor_binding.revision` | integer | Required | Revision of the approved competitor set bound to this offer or run. Pass the current set revision as revision when preparing an offer. maximum: `9007199254740991`; exclusiveMinimum: `0` |
  | `competitor_binding.memberId` | string | Required | Identifier returned by the related operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `scope` | object | Required | additional fields rejected |
  | `scope.domain` | string | Required | |
  | `scope.include_subdomains` | boolean | Required | |
  | `items` | array | Required | Records in this bounded page. maxItems: `100` |
  | `items[].id` | string | Required | Resource identifier returned by the operation. pattern: `"^[a-zA-Z0-9_-]{1,128}$"` |
  | `items[].created_at` | string | Required | UTC timestamp when the record was created. format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `items[].expires_at` | string | Required | format: `"date-time"`; pattern: `"^(?:(?:\\d\\d[2468][048]\|\\d\\d[13579][26]\|\\d\\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\\d\|30)\|(?:02)-(?:0[1-9]\|1\\d\|2[0-8])))T(?:(?:[01]\\d\|2[0-3]):[0-5]\\d:[0-5]\\d\\.\\d{3}(?:Z))$"` |
  | `next_cursor` | string / null | Required | Opaque continuation for the same listing; null means no further page. |
  | `has_more` | boolean | Required | True when another page is available. |
  | `page` | object | Required | additional fields rejected |
  | `page.limit` | integer | Required | maximum: `9007199254740991`; exclusiveMinimum: `0` |
  | `page.sort` | string | Required | |
  | `page.order` | string | Required | values: `"asc"`, `"desc"` |
  | `page.total` | integer / null | Required | |
  | `page.query_scope` | string | Required | must equal `"server_dataset"` |
  | `page.nulls` | string | Required | must equal `"last"` |
</Accordion>

[Download input schema](/schemas/list_competitor_analyses.input.json) · [Download output schema](/schemas/list_competitor_analyses.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 `COMPETITOR_ANALYSIS_UNAVAILABLE`, `INVALID_COMPETITOR_ANALYSIS_INPUT`, `COMPETITOR_SET_NOT_FOUND`, `COMPETITOR_MEMBER_NOT_FOUND`, `COMPETITOR_REVISION_CONFLICT`, `COMPETITOR_ANALYSIS_AUTHORITY_CHANGED`, `COMPETITOR_ANALYSIS_EVIDENCE_CHANGED`, `INVALID_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

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 |
| - | - | - |
| `GET /v1/competitor-analyses` | 200 | Supply projectId, setId, revision and memberId in the query. Returns retained analyses without enqueueing work. |

## Continue

[get\_competitor\_analysis](/reference/commands/get_competitor_analysis)

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