---
title: "Claim the next batch of one pipeline's available tasks"
method: POST
path: "/v1/agent-tasks/claim-next"
tags: ["Agent Tasks"]
---

# Claim the next batch of one pipeline's available tasks

`POST /v1/agent-tasks/claim-next`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/agent-tasks/claim-next`
- Auth: HTTP bearer

Claims up to `count` (1-50, default 10) available tasks of the pipeline, oldest first, and returns their full payloads. Each claim is the ordinary row-locked claim, so parallel agents get disjoint tasks; a task another agent took in the meantime is skipped. Returns an empty `data` array when nothing is available.

## Request body

- object
  - `pipeline_id` string, uuid, required
  - `count` integer

## Response `200`

The claimed tasks (full payloads) and how many were claimed.

- object
  - `data` AgentTaskPayload[]
    - `id` string, uuid, required
    - `customer_id` string, uuid, required
    - `pipeline_id` string, uuid, required
    - `grain` 'document' | 'product', required: document = one parked document at an Agent (via MCP) rail stage; product = one composed record at the post-assembly Agentic Review stage.
    - `pipeline_document_id` string, uuid, nullable, required: Set on document-grain tasks only.
    - `document_id` string, uuid, nullable, required: Set on document-grain tasks only.
    - `record_id` string, uuid, nullable, required: The composed record under review; set on product-grain tasks only.
    - `stage_id` string, required
    - `phase_index` integer, required
    - `status` 'available' | 'claimed' | 'submitted' | 'timed_out' | 'cancelled', required
    - `execution_epoch` integer, required
    - `claimed_at` string, date-time, nullable
    - `lease_expires_at` string, date-time, nullable
    - `timeout_at` string, date-time, required
    - `submitted_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `result_summary` AgentTaskResultSummary, nullable: Present only on a task the caller itself submitted (the submit response, and `GET /v1/agent-tasks/{id}` by the claim holder). What the platform did with the submit; keys with nothing to report are omitted.
      - `fields` string[]: Fields written as submitted.
      - `summary` string
      - `demoted_below_floor` string[]: Values under the autonomy contract's confidence floor; recorded
      - `skipped_cells` object[]: Fields the cell-write guard withheld. `review_authority` = a review decision outranks the agent; `pending_approval` = the cell is held for review. Under `releaseHolds`, a `pending_approval` field also appears in `released_holds` or `release_failed`.
        - `field_key` string
        - `reason` 'review_authority' | 'pending_approval'
      - `escalated` object[]: Fields handed to a human (agent escalation or an unverified quote).
        - `field_key` string
        - `reason` string
        - `proposed` unknown
      - `released_holds` object[]: Product grain with the autonomy contract's `releaseHolds`: held fields the submit settled through the review path (`approve` = held value kept, `correct` = submitted value written; a null value clears the field).
        - `field_key` string
        - `action` 'approve' | 'correct'
        - `pipeline_document_id` string, uuid
      - `release_failed` object[]: Held fields the release could not settle; they stay held for a human.
        - `field_key` string
        - `reason` string
      - `anchor_election` string, uuid
      - `autonomy_mode` 'propose' | 'observe'
    - `input_snapshot` object, required: Immutable latest-cell snapshot captured when the document reached the Agent (via MCP) stage.
    - `output_contract` object[], required
      - `key` string, required
      - `dataType` 'string' | 'number' | 'date' | 'boolean' | 'object' | 'array', required
      - `required` boolean, required
      - `description` string: The Spec field description (the field's rules), frozen when the task was created.
      - `enumValues` string[]: Allowed codes of a closed enum field
    - `instructions` string, nullable
    - `timeout_fallthrough` 'hold' | 'skip' | 'route_to_review', required
  - `claimed` integer

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)