Skip to main content

talonic_list_decision_tasks

List the decision tasks of one Talonic App, newest first. A decision task is how an External-mode app hands a run's decision to an agent outside the platform: the run assembles its input package, freezes it, enters awaiting_decision, and offers a task. This tool is the polling alternative to the app.decision_task.offered webhook and the entry point of the decision workflow.

Each row in data[] carries identifiers (id, run_id, app_id), the lifecycle status, the current execution_epoch, the lease settings (lease_seconds, claimed_by, claimed_at, lease_expires_at, heartbeat_at), the hard sla_deadline_at, and submitted_at / created_at. The input package is never inlined here: it is read page by page after a claim, and every page read is journaled onto the run.

Every one of these tools runs at the platform's decide tier. A tlnc_ workspace API key needs a decide grant on the app. An OAuth connector session (Claude.ai) needs the apps:decide scope — consented in person when the connector is added, never pre-consented — plus a live workspace role of senior_member or above; the claim is then recorded as the client acting for that person ("Claude for Jane Doe"). Web sessions are refused. A 403 names what is missing (decide_grant_required, insufficient_scope, insufficient_tier); the agent should report it rather than retry.

The decision workflow

  1. Call talonic_list_decision_tasks with the app_id and status: "available".
  2. Claim a task with talonic_claim_decision_task; the claim returns the output contract, precedents and the package descriptor.
  3. Read the frozen input package with talonic_read_decision_package, page by page from package.first_cursor.
  4. Heartbeat with talonic_heartbeat_decision_task while deciding, then finish with talonic_submit_decision_task — or talonic_release_decision_task / talonic_fail_decision_task.
ParameterTypeDescription
app_id *UUIDThe External-mode app whose inbox to read.
statusavailable | claimed | submitted | released | failed | timed_out | cancelledOptional lifecycle-state filter. Start with `available` when looking for work.
limitintegerPage size from 1 to 100. Defaults to 50.
cursorstringOpaque `pagination.next_cursor` from the previous page.
Tool input and response
// talonic_list_decision_tasks({ "app_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "status": "available", "limit": 1 })
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "customer_id": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
      "run_id": "22222222-2222-4222-8222-222222222222",
      "app_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
      "status": "available",
      "execution_epoch": 0,
      "input_package_ref": "run",
      "lease_seconds": 120,
      "claimed_by": null,
      "claimed_at": null,
      "lease_expires_at": null,
      "heartbeat_at": null,
      "sla_deadline_at": "2026-09-22T10:10:00.000Z",
      "submitted_at": null,
      "created_at": "2026-09-22T10:00:00.000Z",
      "updated_at": "2026-09-22T10:00:00.000Z"
    }
  ],
  "pagination": { "has_more": false, "next_cursor": null }
}

sla_deadline_at is the decision SLA (default 10 minutes, configurable per app): if no valid decision arrives by then, the platform applies the app's declared fallback policy — a resident rule set decides, the run parks as a system-raised review, or the run fails. Filtering by claimed or timed_out is useful for supervision; a task whose lease expired is eligible for reclaiming.

Frequently asked questions

How is a decision task different from an Agent task?+
An Agent task parks one document at a pipeline stage and asks for declared output fields. A decision task parks one App run and asks for the run's decision: the outcome is validated against the app's output contract, must cite evidence from the frozen input package, and is written to the app's ledger with decided_by.type external_agent. The two protocols share the lease, heartbeat and execution-epoch mechanics.
Why does the tool return 403 insufficient_scope, or carry talonic/can_invoke: false in its _meta?+
The decide tier is an independent grant: operate does not imply it. A tlnc_ key needs a decide grant on that app, granted by a workspace owner. An OAuth connector session needs the apps:decide scope and a senior_member role or above, read live on every call. If the connector was added before the scope existed, its token lacks it: the hosted server then lists the seven tools flagged with _meta.talonic/can_invoke: false (descriptions stay unchanged), and the fix is to remove and re-add the Talonic connector so the consent screen offers 'Claim and decide tasks'.
What do the decision task statuses mean?+
available means no one holds the task; claimed means an agent holds a live lease; submitted means a decision was accepted and the run resumed; released means the claimant gave it back (it returns to available); failed means the claimant declared it undecidable and the fallback applied; timed_out means the SLA passed; cancelled means the run was cancelled or the task withdrawn.

Related

talonic_claim_decision_task
talonic_read_decision_package
talonic_submit_decision_task
talonic_list_agent_tasks