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

# Request target check

> Queue a metered destination health check.

`request_target_check`

Queue a metered destination health check. Reuse the idempotency key for a retry; blocked results remain unknown.

<Note>Hosted MCP registration verified. These schemas describe the development contract; confirm supported inputs with tools/list. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.</Note>

| Access          | Behavior              |
| --------------- | --------------------- |
| `watches:write` | Writes or admits work |

Checks and monitoring can consume workspace capacity. Queued admission is not a completed observation; inspect the returned job or saved state.

## 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": "request_target_check",
      "arguments": {
        "targetId": "target_example",
        "idempotencyKey": "docs-request-001"
      }
    }
  }
  ```

  ```bash CLI theme={null}
  linktrail call request_target_check --args '{"targetId":"target_example","idempotencyKey":"docs-request-001"}'
  ```

  ```bash HTTP theme={null}
  curl "$LINKTRAIL_API_URL/v1/commands/request_target_check" \
    -H "Authorization: Bearer $LINKTRAIL_API_KEY" \
    -H 'Content-Type: application/json' \
    --data '{"targetId":"target_example","idempotencyKey":"docs-request-001"}'
  ```
</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}
{
  "id": "target_job_example",
  "workspace_id": "ws_example",
  "project_id": "pr_example",
  "state": "queued",
  "idempotency_key": "docs-request-001",
  "payload_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "attempt_count": 0,
  "max_attempts": 3,
  "lease_token": null,
  "lease_expires_at": null,
  "error_code": null,
  "created_at": "2026-09-13T12:00:00.000Z",
  "updated_at": "2026-09-13T12:00:00.000Z",
  "completed_at": null,
  "target_id": "target_example",
  "replayed": false
}
```

## 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                                                                                                          |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `targetId`       | string | Required | Identifier of the target returned by its create or list operation. minLength: 1; maxLength: 200                                  |
| `idempotencyKey` | string | Required | Caller-generated key reused only for retries of the same operation and arguments in this workspace. minLength: 1; maxLength: 200 |

### Validation and omitted values

Save the returned job identifier and read get\_target\_job. Destination jobs and evidence are independent of source-link presence.

Reuse the original idempotencyKey after a lost response. A paused or already-busy destination needs its current state inspected before new 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.

| Field              | Type          | Presence | Meaning and constraints                                                                                                           |
| ------------------ | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string        | Required | Resource identifier returned by the operation.                                                                                    |
| `state`            | string        | Required | Saved lifecycle or evidence state, as enumerated for this record. values: "queued", "running", "succeeded", "failed", "cancelled" |
| `workspace_id`     | string        | Required | Workspace that owns this record.                                                                                                  |
| `project_id`       | string        | Required | Project that owns this record.                                                                                                    |
| `watch_id`         | string        | Optional | watch id recorded for this result.                                                                                                |
| `target_id`        | string        | Optional | target id recorded for this result.                                                                                               |
| `type`             | string        | Optional | type recorded for this result.                                                                                                    |
| `execution_mode`   | string        | Optional | execution mode recorded for this result.                                                                                          |
| `idempotency_key`  | string        | Required | Caller retry identifier, bound to the original request arguments.                                                                 |
| `payload_hash`     | string        | Required | payload hash recorded for this result.                                                                                            |
| `attempt_count`    | number        | Required | attempt count recorded for this result.                                                                                           |
| `max_attempts`     | number        | Required | max attempts recorded for this result.                                                                                            |
| `lease_token`      | string / null | Required | lease token recorded for this result.                                                                                             |
| `lease_expires_at` | string / null | Required | lease expires at recorded for this result.                                                                                        |
| `error_code`       | string / null | Required | error code recorded for this result.                                                                                              |
| `error_message`    | string / null | Optional | error message recorded for this result.                                                                                           |
| `created_at`       | string        | Required | UTC timestamp when the record was created.                                                                                        |
| `updated_at`       | string        | Required | UTC timestamp of the last record update.                                                                                          |
| `completed_at`     | string / null | Required | completed at recorded for this result.                                                                                            |
| `replayed`         | boolean       | Optional | True when the response reuses an earlier request with the same idempotency value.                                                 |
| `usage`            | object / null | Optional | usage recorded for this result.                                                                                                   |
| `usage.units`      | number        | Required | units recorded for this result.                                                                                                   |
| `usage.state`      | string        | Required | Saved lifecycle or evidence state, as enumerated for this record.                                                                 |
| `usage.period`     | string        | Required | period recorded for this result.                                                                                                  |

[Download input schema](/schemas/request_target_check.input.json) · [Download output schema](/schemas/request_target_check.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                                                                                                                   |
| ------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/targets/{targetId}/recheck` | 202     | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. |

## Continue

[get\_target\_job](/reference/commands/get_target_job) · [get\_target\_history](/reference/commands/get_target_history)

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