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

# Get competitor refresh

> Read a competitor refresh schedule and the latest cycle counts.

`get_competitor_refresh`

Read a competitor refresh schedule and the latest cycle counts. Missing rows remain limited to the selected corpus and never prove a link was lost.

<Note>Available in the deployed MCP and HTTP bundle. Confirm access and inputs with your connected catalog. 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": "get_competitor_refresh",
      "arguments": {
        "setId": "set_example"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  agentlinkops call get_competitor_refresh --args '{"setId":"set_example"}'
  ```

  ```bash HTTP theme={null}
  curl "$AGENTLINKOPS_API_URL/v1/commands/get_competitor_refresh" \
    -H "Authorization: Bearer $AGENTLINKOPS_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"setId":"set_example"}'
  ```
</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}
{
  "schedule": {
    "v": 1,
    "set_id": "set_example",
    "set_revision": 1,
    "cadence": "weekly",
    "paused": false,
    "last_started_at": null,
    "last_completed_at": null,
    "next_due_at": "2026-09-13T12:00:00.000Z",
    "member_limit": 2,
    "budget_unit": "owned_inventory_lookups"
  },
  "latest_cycle": null
}
```

## 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                                                                      |
| ------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `setId` | string | Required | Identifier of the set returned by its create or list operation. minLength: 1; maxLength: 200 |

### Validation and omitted values

No saved schedule returns schedule and latest\_cycle as null. Reading an existing schedule does not require new discovery admission.

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

* **`schedule`** (object / null, required).
* **`latest_cycle`** (object / null, required).

<Accordion title="All fields and nested objects">
  | Field                          | Type          | Presence | Meaning and constraints                                                                                                                                                                                                                                                                                                                  |
  | ------------------------------ | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `schedule`                     | object / null | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `schedule.v`                   | number        | Required | must equal 1                                                                                                                                                                                                                                                                                                                             |
  | `schedule.set_id`              | string        | Required | Identifier returned by the related operation. minLength: 1; maxLength: 128                                                                                                                                                                                                                                                               |
  | `schedule.set_revision`        | integer       | Required | maximum: 9007199254740991; exclusiveMinimum: 0                                                                                                                                                                                                                                                                                           |
  | `schedule.cadence`             | string        | Required | values: "weekly", "biweekly", "monthly"                                                                                                                                                                                                                                                                                                  |
  | `schedule.paused`              | boolean       | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `schedule.last_started_at`     | string / null | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `schedule.last_completed_at`   | string / null | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `schedule.next_due_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))\$" |
  | `schedule.member_limit`        | number        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `schedule.budget_unit`         | string        | Required | must equal "owned\_inventory\_lookups"                                                                                                                                                                                                                                                                                                   |
  | `latest_cycle`                 | object / null | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.id`              | string        | Required | Resource identifier returned by the operation.                                                                                                                                                                                                                                                                                           |
  | `latest_cycle.state`           | string        | Required | Saved lifecycle or evidence state, as enumerated for this record. values: "running", "completed", "partial", "failed"                                                                                                                                                                                                                    |
  | `latest_cycle.planned_members` | number        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.captured`        | number        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.failed`          | number        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.pending`         | number        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.started_at`      | string        | Required |                                                                                                                                                                                                                                                                                                                                          |
  | `latest_cycle.finished_at`     | string / null | Required |                                                                                                                                                                                                                                                                                                                                          |
</Accordion>

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

## Errors and retries

The command is annotated idempotent. Reuse an accepted idempotency key when the input provides one; changing the payload under a reused key can conflict.

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-sets/{setId}/refresh` | 200     | Remaining read arguments go in query parameters. |

## Continue

[set\_competitor\_refresh\_paused](/reference/commands/set_competitor_refresh_paused)

Follow the [related workflow](/guides/competitor-research), inspect [capability status](/capability-status), or return to the [command index](/reference/index).