Agent Tasks

List and inspect Agent tasks parked by a Spec's Agent (via MCP) stage with GET /v1/agent-tasks: status filter, cursor pagination, input snapshots and contracts.

A Spec's pipeline rail can include an Agent (via MCP) stage: when a document reaches that stage, the pipeline parks it and creates an agent task — an immutable work item holding a snapshot of the document's current cells, an output contract naming the fields the agent must fill, and the stage's instructions. An external agent (typically connected over MCP) pulls the task, does its work with whatever tools it has, and submits values; the pipeline then resumes at the next stage.

A second stage type shares the same transport: Agentic Review runs post-assembly, creating one *product-grain* task per composed record instead of one per document. Its snapshot carries the composed cells plus, per contract field, the full distribution of document-level candidate values the composed value collapsed from — so a reviewing agent adjudicates evidence without re-reading documents. Submissions from these tasks land as canonical cells on the composed record under the actor label "Agentic Review".

GET /v1/agent-tasks lists your workspace's document-scoped tasks, newest first, with read scope. Filter with ?status (one of available, claimed, submitted, timed_out, cancelled — anything else is a 400), page with ?limit (1–100, default 50) and the opaque ?cursor returned as pagination.next_cursor. The listing is keyset-paginated on (created_at, id), so pages stay stable while new tasks are created ahead of your cursor.

Every route on this surface requires the credential to resolve to exactly one tenant. A key operating in the cross-tenant master view gets 400 with the message Select one tenant for Agent task access — task snapshots contain document values, and cross-tenant reads of that payload are never allowed. Additionally, Sources-IAM is evaluated as the user who created the API key: a task whose document sits behind a source restriction that principal is not admitted to is simply invisible (404 on fetch, absent from the list), never a 403.

GET /v1/agent-tasks/:id returns the full payload: the listing's metadata plus input_snapshot (the parked record's cells — and for product-grain tasks the candidates distributions, the frozen autonomy contract, the anchor document, and the triggers that parked it), output_contract (the declared output fields with key, dataType, required), free-text instructions, and timeout_fallthrough (what happens if no agent answers in time: hold, skip, or route_to_review).

The list endpoint returns document-scoped tasks (each row carries document_id and pipeline_document_id). Product-grain Agentic Review tasks are usually bound to a specific agent credential and addressed by id — a claim or fetch by id works for both grains.

GET/v1/agent-tasks

Query parameters

statusstringFilter to one status: available, claimed, submitted, timed_out, or cancelled. Any other value is rejected 400 ("Invalid agent task status").

limitintegerPage size, 1–100. Out-of-range or non-integer values are rejected 400 ("limit must be 1..100"). Default: 50

cursorstringOpaque pagination cursor from a previous response's pagination.next_cursor. A malformed cursor is rejected 400 ("Invalid cursor").

curl

curl -s "https://api.talonic.com/v1/agent-tasks?status=available&limit=25" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response (200)

{
  "data": [
    {
      "id": "0b6a2f5e-8c1d-4e7a-9f3b-2d4c6e8a0b1c",
      "customer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "pipeline_id": "1a0c681d-ea20-4bb4-8892-01a6d7f834da",
      "pipeline_document_id": "e2b8d4f6-1a3c-5e7f-9b1d-3f5a7c9e1b3d",
      "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "stage_id": "agent-1",
      "phase_index": 3,
      "status": "available",
      "execution_epoch": 0,
      "claimed_at": null,
      "lease_expires_at": null,
      "timeout_at": "2026-08-29T14:30:00.000Z",
      "submitted_at": null,
      "created_at": "2026-08-29T12:30:00.000Z",
      "updated_at": "2026-08-29T12:30:00.000Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

Get a task

GET/v1/agent-tasks/:id

Path parameters

id*uuidThe agent task id, from the listing or from your Spec's agent-stage configuration flow.

Response (200) — document-grain task

{
  "id": "0b6a2f5e-8c1d-4e7a-9f3b-2d4c6e8a0b1c",
  "status": "available",
  "stage_id": "agent-1",
  "phase_index": 3,
  "execution_epoch": 0,
  "timeout_at": "2026-08-29T14:30:00.000Z",
  "input_snapshot": {
    "document": { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "filename": "policy-0091.pdf" },
    "recordSetId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "recordId": "e2b8d4f6-1a3c-5e7f-9b1d-3f5a7c9e1b3d",
    "cells": [
      {
        "fieldKey": "policy_number",
        "dataType": "string",
        "value": null,
        "status": "empty",
        "confidence": null,
        "source": "llm_extraction",
        "auditRef": null
      }
    ]
  },
  "output_contract": [
    { "key": "policy_number", "dataType": "string", "required": true },
    { "key": "policy_holder", "dataType": "string", "required": false }
  ],
  "instructions": "Look up the policy number in the carrier portal if it is not printed on the document.",
  "timeout_fallthrough": "route_to_review"
}

The input snapshot is frozen at park time — it reflects the record as the pipeline saw it when the document reached the Agent stage, not the live grid. Field keys inside input_snapshot and output_contract use the stored camelCase JSON shape (fieldKey, dataType, auditRef), unlike the snake_case top-level metadata.

Errors

Error responses

400VALIDATION_ERRORMaster-view credential ("Select one tenant for Agent task access"), an unknown status value, a malformed cursor, or an out-of-range limit.

401unauthorizedMissing or invalid API key.

404RESOURCE_NOT_FOUNDNo such task in your workspace — including tasks whose document is hidden from the key creator by a Sources-IAM rule.

Frequently asked questions

Why does GET /v1/agent-tasks return 400 "Select one tenant for Agent task access"?+

Your credential is operating in the cross-tenant master view. Agent task payloads contain document values, so every route on this surface requires the key to resolve to exactly one workspace tenant. Use a key minted inside the workspace whose tasks you want to work.

Why can't I see a task that I know exists?+

Sources-IAM is evaluated as the user who created your API key. If the task's document comes from a source that principal is not admitted to, the task is invisible: absent from the list and 404 on direct fetch. Have a user with access to that source mint the key, or open the source's IAM rules.

What is the difference between a document-grain and a product-grain task?+

A document-grain task parks one document at an Agent (via MCP) rail stage mid-pipeline; its snapshot is that document's cells. A product-grain task comes from the post-assembly Agentic Review stage: one task per composed record, whose snapshot additionally carries per-field candidate distributions, the frozen autonomy contract, and the group's anchor document.

How long do tasks stay available?+

Each task carries a timeout_at deadline frozen from the Spec's stage configuration. A task nobody submits by then transitions to timed_out and the document proceeds per timeout_fallthrough: hold keeps it parked for a human, skip continues the pipeline without the agent's fields, and route_to_review sends the contract fields to the review queue.

Is polling the list rate-limited separately from my other traffic?+

Agent task routes are metered under the standard platform read namespace with your key's daily tier quota. Poll at a sensible interval — for most integrations, listing ?status=available every 30–60 seconds per pipeline burst is plenty, since tasks also remain claimable the moment they appear.

Claim, Heartbeat & Submit

Agent Tasks

Get a task

Errors

Frequently asked questions

Related