Get Agent HIL Review

Return the managed-agent review state for a single human-in-the-loop block in a workflow run. An agent review is spawned when the block’s agent_in_the_loop config is pre_review, review, or auto. The agent inspects the document, grounds each flagged field, and produces a structured proposal (approve / approve‑with‑modified_data / reject / escalate). This endpoint exposes that proposal and its current dispatch state. Returns 404 when no agent review has been spawned for the (run_id, block_id) pair — either because the block has agent_in_the_loop="disabled", or because the workflow hasn’t reached the block yet.

When to use it

The dashboard’s review panel polls this to render the agent’s proposal alongside the human verification form.
Backend consumers (audit pipelines, eval jobs) can read it to inspect the agent’s confidence + evidence after a run completes.
It does NOT submit a decision. Agent proposals are submitted via the agent’s custom-tool callback inside the Temporal activity, not via HTTP. To submit a human decision (or to apply / override the agent’s proposal), use Submit HIL Decision.

Response — key fields

Field	Notes
`mode`	`"pre_review"` / `"review"` / `"auto"` — how the agent’s proposal is dispatched.
`status`	Lifecycle: `queued` → `running` → terminal (`proposed`, `submitted`, `escalated`, `failed`, `superseded_by_human`).
`proposed_decision.approved`	`true` / `false` / `null` (when escalating).
`proposed_decision.modified_data`	The replacement payload the agent suggests (only when it proposed corrections).
`proposed_decision.confidence`	Float 0–1. Auto-mode auto-submits only when ≥ `auto_threshold`.
`proposed_decision.evidence`	One item per verified field, each with a literal `quote` from the document, a `source` pointer (page / char_range), and the action taken (`approved_unchanged` / `modified` / `rejected`).
`proposed_decision.changed_paths`	Sub-paths of `extracted_data` the agent modified.
`proposed_decision.escalate`	`true` when the agent could not confidently decide. `escalation_reason` carries the explanation.
`submitted_hil_command_id`	Populated when `status="submitted"` — deterministic id of the HIL decision the workflow applied.
`failure_reason`	Populated when `status="failed"` (timeout, schema-validation failure, session error).
`auto_threshold`, `timeout_seconds`	The config values at spawn time.

Dispatch behaviour by mode

`mode`	Agent confidently approves	Agent approves with corrections	Agent escalates
`pre_review`	`status=proposed`, parked for human	`proposed` with `modified_data`	`proposed`
`review`	`status=submitted`, workflow resumes	`submitted` with the corrected payload	`proposed`, parked
`auto`	`submitted` if `confidence ≥ auto_threshold`, else `escalated`	Same gate	`escalated`

In proposed and escalated, the dashboard’s review panel offers Accept & continue (one-click submit) and Apply to form (pre-fill the human review form with modified_data) when the proposal is actionable.

curl -X GET "https://api.retab.com/v1/workflows/runs/run_abc123/agent-hil-reviews/hil-1" \
  -H "Authorization: Bearer $RETAB_API_KEY"

{
  "id": "agrev_abc",
  "run_id": "run_abc123",
  "block_id": "hil-1",
  "workflow_id": "wf_1",
  "mode": "auto",
  "status": "running",
  "managed_agent_session_id": "sesn_01ABC",
  "proposed_decision": null,
  "submitted_hil_command_id": null,
  "failure_reason": null,
  "auto_threshold": 0.85,
  "timeout_seconds": 900,
  "created_at": "2026-05-13T08:14:02.341Z",
  "updated_at": "2026-05-13T08:14:02.341Z"
}

Authorizations

Api-Key

string

header

required

Path Parameters

run_id

string

required

block_id

string

required

Query Parameters

access_token

string | null

Response

Successful Response

Sidecar persistence row tracking a managed-agent review attempt for one HIL block.

Identity is (tenant scope, run_id, block_id) and is enforced by a unique Mongo index — that is the load-bearing primitive that keeps managed-agent spawning idempotent across Temporal activity retries and double-trigger races.

string

required

Internal id (nanoid).

run_id

string

required

Workflow run id the block belongs to.

block_id

string

required

HIL block id being reviewed.

workflow_id

string

required

Workflow id the run belongs to (denormalized for query convenience).

mode

enum<string>

required

Configured agent_in_the_loop mode at spawn time.

Available options:

pre_review,

review,

auto

auto_threshold

number

required

Snapshot of agent_auto_confidence_threshold at spawn time. Frozen so config edits during the run don't change the gate.

Required range: 0 <= x <= 1

timeout_seconds

integer

required

Snapshot of agent_review_timeout_seconds at spawn time.

Required range: 30 <= x <= 3600

created_at

string<date-time>

required

updated_at

string<date-time>

required

status

enum<string>

default:queued

Lifecycle status of this review attempt.

Available options:

queued,

running,

proposed,

submitted,

escalated,

failed,

superseded_by_human

managed_agent_session_id

string | null

Anthropic Managed Agents session id once spawned.

managed_agent_vault_id

string | null

Anthropic vault id minted at spawn time for this session. Holds the per-org master_key impersonation token. Archived alongside the session at end-of-life.

proposed_decision

ProposedDecision · object

Last proposal received from the agent. Updated on each custom-tool callback.

Show child attributes

submitted_hil_command_id

string | null

HIL command id used when the proposal was submitted via submit_hil_decision_service.

failure_reason

string | null

Free-text reason when status='failed'. Populated by timeout, schema rejection, or session error.

API Reference

Documentation Index

​When to use it

​Response — key fields

​Dispatch behaviour by mode

Authorizations

Path Parameters

Query Parameters

Response

When to use it

Response — key fields

Dispatch behaviour by mode