> ## 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.
# Verify discovery candidates
> Queue checks for 1 to 50 selected stored candidates under one workspace budget reservation.
`verify_discovery_candidates`
Queue checks for 1 to 50 selected stored candidates under one workspace budget reservation. Returns every item outcome, including budget rejections. Replay the same key after a network failure. Verification is asynchronous and does not enroll monitoring.
Development preview. This command is absent from the hosted MCP readback. Generic CLI/HTTP calls require a matching development server. Configure LINKTRAIL\_API\_URL; production does not expose these command routes.
| Access | Behavior |
| --------------------------------- | --------------------- |
| `discovery:read`, `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.
```json MCP theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "verify_discovery_candidates",
"arguments": {
"runId": "run_example",
"items": [
{
"candidateId": "dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
],
"idempotencyKey": "docs-request-001"
}
}
}
```
```bash CLI theme={null}
linktrail call verify_discovery_candidates --args '{"runId":"run_example","items":[{"candidateId":"dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}],"idempotencyKey":"docs-request-001"}'
```
```bash HTTP theme={null}
curl "$LINKTRAIL_API_URL/v1/commands/verify_discovery_candidates" \
-H "Authorization: Bearer $LINKTRAIL_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"runId":"run_example","items":[{"candidateId":"dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}],"idempotencyKey":"docs-request-001"}'
```
## 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}
{
"schema_version": 1,
"id": "batch_example",
"workspace_id": "ws_example",
"project_id": "pr_example",
"run_id": "run_example",
"created_at": "2026-09-13T12:00:00.000Z",
"state": "pending",
"counts": {
"rejected": 0,
"queued": 1,
"running": 0,
"succeeded": 0,
"failed": 0,
"cancelled": 0
},
"items": [
{
"ordinal": 0,
"candidate_id": "dc_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"local_reference": null,
"job_id": "job_example_1",
"watch_id": "watch_example_1",
"state": "queued",
"error_code": null,
"observation": null,
"usage": {
"unit": "source_check",
"units": 1,
"state": "reserved",
"period": "2026-09"
}
}
],
"reservation": {
"units": 1,
"outstanding": 1,
"consumed": 0,
"released": 0,
"period": "2026-09"
},
"recurring_monitoring_created": false,
"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 |
| ------------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `runId` | string | Required | Identifier of the run returned by its create or list operation. pattern: "^\[a-zA-Z0-9\_-]\{1,128}\$" |
| `items` | array | Required | The items value; allowed values and bounds are specified in this schema. minItems: 1; maxItems: 50 |
| `items[].candidateId` | string | Required | Identifier returned by the related operation. pattern: "^dc\_\[a-f0-9]\{64}\$" |
| `items[].localReference` | string | Optional | See the typed schema and response example for this field. minLength: 1; maxLength: 200 |
| `idempotencyKey` | string | Required | Caller-generated key reused only for retries of the same operation and arguments in this workspace. pattern: "^\[\x21-\x7e]\{1,200}\$" |
### Validation and omitted values
Every item belongs to one saved run; candidate IDs must be selected deliberately. Omitted per-item localReference remains null.
Save the batch identifier and inspect every per-item outcome. Budget refusals and completed unknown observations remain explicit; no recurring monitoring is created.
## 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 |
| -------------------------------- | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `schema_version` | number | Required | schema version recorded for this result. must equal 1 |
| `id` | string | Required | Resource identifier returned by the operation. |
| `workspace_id` | string | Required | Workspace that owns this record. |
| `project_id` | string | Required | Project that owns this record. |
| `run_id` | string | Required | run id recorded for this result. |
| `state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: "pending", "completed", "partial", "failed" |
| `counts` | object | Required | counts recorded for this result. additional fields rejected |
| `counts.rejected` | integer | Required | rejected recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `counts.queued` | integer | Required | queued recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `counts.running` | integer | Required | running recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `counts.succeeded` | integer | Required | succeeded recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `counts.failed` | integer | Required | failed recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `counts.cancelled` | integer | Required | cancelled recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `items` | array | Required | Records in this bounded page. minItems: 1; maxItems: 50 |
| `items[].ordinal` | integer | Required | ordinal recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `items[].candidate_id` | string | Required | candidate id recorded for this result. |
| `items[].local_reference` | string / null | Required | Customer reference for joining this record to a local ledger entry. |
| `items[].job_id` | string / null | Required | job id recorded for this result. |
| `items[].watch_id` | string / null | Required | watch id recorded for this result. |
| `items[].state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. values: "rejected", "queued", "running", "succeeded", "failed", "cancelled" |
| `items[].error_code` | string / null | Required | error code recorded for this result. |
| `items[].observation` | object / null | Required | observation recorded for this result. |
| `items[].observation.id` | string | Required | Resource identifier returned by the operation. |
| `items[].observation.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].observation.reason` | string / null | Required | Recorded explanation; null when no explanation applies. |
| `items[].observation.checked_at` | string | Required | UTC timestamp of the saved check. |
| `items[].usage` | object / null | Required | usage recorded for this result. |
| `items[].usage.unit` | string | Required | unit recorded for this result. must equal "source\_check" |
| `items[].usage.units` | number | Required | units recorded for this result. |
| `items[].usage.state` | string | Required | Saved lifecycle or evidence state, as enumerated for this record. |
| `items[].usage.period` | string | Optional | period recorded for this result. |
| `reservation` | object / null | Required | reservation recorded for this result. |
| `reservation.units` | integer | Required | units recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `reservation.outstanding` | integer | Required | outstanding recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `reservation.consumed` | integer | Required | consumed recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `reservation.released` | integer | Required | released recorded for this result. minimum: 0; maximum: 9007199254740991 |
| `reservation.period` | string | Required | period recorded for this result. |
| `replayed` | boolean | Optional | True when the response reuses an earlier request with the same idempotency value. |
| `recurring_monitoring_created` | boolean | Required | Whether this operation enrolled recurring monitoring. must equal false |
| `created_at` | string | Required | UTC timestamp when the record was created. |
[Download input schema](/schemas/verify_discovery_candidates.input.json) · [Download output schema](/schemas/verify_discovery_candidates.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/discovery/runs/{runId}/verification-batches` | 202 | Remaining arguments go in a JSON object body. Supply idempotencyKey as the Idempotency-Key header on this resource route. Returns 202 for pending batches and 200 otherwise. |
## Continue
[get\_candidate\_verification\_batch](/reference/commands/get_candidate_verification_batch)
Follow the [related workflow](/guides/import-and-verify), inspect [capability status](/capability-status), or return to the [command index](/reference/index).