# Human in the Loop

The Human in the Loop block pauses workflow execution and waits for human intervention before continuing. Use it to add approval gates, collect feedback, or gather additional input at critical decision points.

![Human in the Loop Block Configuration](https://docs.steelengine.com/static/blocks/hitl-1.png)

When execution reaches this block, the workflow waits for a human to approve or deny it. They can do so in SteelEngine, through the approval portal, the API, or a webhook. Without a configured [workflow timeout](/execution#workflow-timeouts), the pause can wait indefinitely. With a hard timeout, the original deadline continues during the pause and ends the run if no decision arrives in time. Resuming does not restart the timeout clock.

![Human in the Loop Approval Portal](https://docs.steelengine.com/static/blocks/hitl-2.png)

## Configuration Options

### Display Data

Defines what data is displayed to the approver. This is the context shown in the approval portal to help them make an informed decision.

Use the visual builder or JSON editor to structure the data. Reference workflow variables using `<blockName.output>` syntax.

```json
{
  "customerName": "<agent1.content.name>",
  "proposedAction": "<router1.selectedPath>",
  "confidenceScore": "<evaluator1.score>",
  "generatedEmail": "<agent2.content>"
}
```

### Notification

**Notification Type** chooses how approvers learn that an approval is waiting:

* **Internal Notification** (default) - Alerts approvers inside SteelEngine with an entry in their Notifications inbox
* **Internal + External Tools** - The internal notification plus the tools configured below
* **External Tools Only** - Only the tools configured below

**External Notification Tools** appears for the two external modes. Add any integration tool (Slack, Gmail, Microsoft Teams, a webhook, and so on). Each tool runs when the block pauses and receives the review link to include in its message. Reference the approval URL as `<blockId.url>`.

**Additional Approvers** takes a comma-separated list of organization members' email addresses. SteelEngine always notifies the workflow owner and whoever started the run. It also notifies the people listed here.

### Resume Form

Defines the fields approvers fill in when responding. This data becomes available to downstream blocks after the workflow resumes.

```json
{
  "approved": {
    "type": "boolean",
    "description": "Approve or reject this request"
  },
  "comments": {
    "type": "string",
    "description": "Optional feedback or explanation"
  }
}
```

Access resume data in downstream blocks using `<blockId.fieldName>`.

## Approve and Deny

Every resume carries a decision. It is `approved` unless the resume input sets `_humanInTheLoopDecision` (or `decision`) to `denied` or `rejected`. The in-app **Deny** buttons set it for you. The portal's **Approve and resume** button and a plain API resume default to approved. A denial may include a reason in `rejectionReason`, `denyReason`, or `reason`. Without one, SteelEngine records the reason as "Human approval was denied."

On approval, execution continues along the block's normal connections. On denial, the block output gains `denied: true`, `error`, `rejectionReason`, and `deniedAt`, and execution follows the block's error output handle. If nothing is connected to the error handle, the run stops at the block.

## Approval Methods

**In SteelEngine**

### In SteelEngine

Pending approvals surface in three places for signed-in members:

* The [**Notifications**](/execution/notifications) page lists every pending approval in the organization under **Waiting on you**, whatever the block's Notification Type. **Review** opens the approval with **Approve** and **Deny** buttons
* The workflow editor's block panel lists the block's pending approvals with the same **Approve** and **Deny** actions
* Each notified approver receives an internal notification titled "Approval needed: (workflow name)" that links to the approval

Denying from these surfaces sets the decision to denied. The editor's **Deny** accepts an optional reason.

**Approval Portal**

### Approval Portal

Every paused execution has a portal URL (`<blockId.url>`) of the form `/resume/{workflowId}/{executionId}`, optionally with `?contextId=...` to preselect one pause point. Opening it takes the approver to the [**Notifications**](/execution/notifications) page of the workflow's workspace with that approval open for review, showing the Display Data, the Resume Form fields, and **Approve** and **Deny** buttons.

The portal is part of the signed-in app: approvers must have a SteelEngine account with access to the workflow. A signed-out visitor is asked to log in first and then returns to the approval. A signed-in visitor without access sees a no-access page, with **Request access** when the organization's access rules allow it. A missing workflow shows an unavailable page. Share the URL in notifications for approvers to review and respond.

Once an approval is decided, the review shows the decision, who made it, and when. A decision submitted with an API key names the key instead of a person.

**API**

### REST API

Programmatically resume workflows using the resume endpoint. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused execution response.

The API reference has the full request and response schemas for [List Paused Executions](/api-reference/workflows/listPausedExecutions), [Get Paused Execution](/api-reference/workflows/getPausedExecution), and [Resume Execution](/api-reference/workflows/resumeExecution).

```bash
POST /api/resume/{workflowId}/{executionId}/{contextId}
Content-Type: application/json
X-API-Key: your-api-key

{
  "input": {
    "approved": true,
    "comments": "Looks good to proceed"
  }
}
```

To deny, add the decision to the input: `{"input": {"_humanInTheLoopDecision": "denied", "rejectionReason": "Budget not approved"}}`.

Each resume request chooses its own response mode. The mode used by the original execute call does not constrain the resume response.

* **Sync mode** (default) — The response waits for the remaining workflow to complete and returns the full result:

```json
{
  "success": true,
  "status": "completed",
  "executionId": "<resumeExecutionId>",
  "output": { ... },
  "metadata": { "duration": 1234, "startTime": "...", "endTime": "..." }
}
```

If the resumed workflow hits another HITL block, the response returns `"status": "paused"` with new `_resume` URLs in the output.

If the synchronous wait reaches its request timeout while the durable execution is still running, the API returns `202` with `"status": "processing"` and a `statusUrl` instead of cancelling the workflow.

* **Stream mode** — Request SSE on the resume call with `Accept: text/event-stream` or `X-Stream-Response: true`:

```bash
curl -N -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"input":{"approved":true}}' \
  https://your-domain/api/resume/{workflowId}/{executionId}/{contextId}
```

The resume opens a new SSE connection containing only post-resume events. If execution completes or reaches another HITL block, the API emits the final event followed by `[DONE]` and closes the connection. No SSE connection remains open while the workflow waits for human input.

* **Async mode** — Set `X-Execution-Mode: async` on the resume request. The durable resume is accepted and returns immediately with `202`:

```json
{
  "success": true,
  "async": true,
  "status": "accepted",
  "executionId": "<resumeExecutionId>",
  "rootExecutionId": "<rootExecutionId>",
  "statusUrl": "https://your-domain/api/jobs/<resumeExecutionId>"
}
```

If both async and stream headers are present, async mode takes precedence.

#### Other responses

* `200` with `"status": "queued"` and a `queuePosition` — another resume for this execution is already running. Yours runs after it finishes
* `400` — the resume could not be queued. The response body carries the reason
* `409` — "Resume request does not match the durable execution state": the pause point named by `contextId` is not waiting
* `503` — the durable resume service or the resume event stream is temporarily unavailable. Retry later

#### Polling execution status

Use the `statusUrl` returned by an async resume to poll its durable execution status. To inspect an execution that is currently paused:

```bash
GET /api/resume/{workflowId}/{executionId}
X-API-Key: your-api-key
```

The resume GET endpoint returns the paused execution detail with all pause points, their statuses, and resume links, plus `blockNames`, a map from each paused block's ID to its display name. It requires read access to the workflow and never returns the execution's internal state snapshot.

**Webhook**

### Webhook

Set **Notification Type** to one of the external modes and add a webhook tool under **External Notification Tools** to send approval requests to external systems. Integrate with ticketing systems like Jira or ServiceNow.

### Pause Points Inside Loop and Parallel

A Human in the Loop block inside a Loop or Parallel container pauses once per iteration or branch. Each pause has its own `contextId`. The `contextId` is the block ID plus a suffix: the parallel branch index, `_loop<iteration>` for the loop iteration, and `_parents<...>` for enclosing loop iterations. Resume each pause point separately with its own `contextId`. The `GET /api/resume/{workflowId}/{executionId}` endpoint lists them all.

## API Execute Behavior

When triggering a workflow via the execute API (`POST /api/workflows/{id}/execute`), HITL blocks cause the execution to pause and return the `_resume` data in the response:

**Sync (JSON)**

The response includes the full pause data with resume URLs:

```json
{
  "success": true,
  "executionId": "<executionId>",
  "output": {
    "data": {
      "operation": "human",
      "_resume": {
        "apiUrl": "/api/resume/{workflowId}/{executionId}/{contextId}",
        "uiUrl": "/resume/{workflowId}/{executionId}",
        "contextId": "<contextId>",
        "executionId": "<executionId>",
        "workflowId": "<workflowId>"
      }
    }
  }
}
```

**Stream (SSE)**

Blocks before the HITL stream their `selectedOutputs` normally. When execution pauses, the final SSE event includes `status: "paused"` and the `_resume` data:

```
data: {"blockId":"agent1","chunk":"streamed content..."}
data: {"event":"final","data":{"success":true,"output":{...,"_resume":{...}},"status":"paused"}}
data: "[DONE]"
```

A streaming resume uses a new request with `Accept: text/event-stream` or `X-Stream-Response: true`. Blocks after the HITL stream their `selectedOutputs` the same way, and the connection closes again on completion or the next pause.

HITL blocks are automatically excluded from the `selectedOutputs` dropdown since their data is always included in the pause response.

**Async**

Returns `202` immediately. Use the polling endpoint to check when the execution pauses.

## Common Use Cases

**Content Approval** - Review AI-generated content before publishing

```
Agent → Human in the Loop → API (Publish)
```

**Multi-Stage Approvals** - Chain multiple approval steps for high-stakes decisions

```
Agent → Human in the Loop (Manager) → Human in the Loop (Director) → Execute
```

**Data Validation** - Verify extracted data before processing

```
Agent (Extract) → Human in the Loop (Validate) → Function (Process)
```

**Quality Control** - Review AI outputs before sending to customers

```
Agent (Generate) → Human in the Loop (QA) → Gmail (Send)
```

## Block Outputs

**`url`*&#x2A; - Portal URL for the paused execution
&#x2A;*`resumeEndpoint`*&#x2A; - Resume API endpoint URL for this pause point
&#x2A;*`response`** - The pause response object: `data` (`operation`, `responseStructure` describing the Display Data, `inputFormat`, the `_resume` links, and after resume `submission`, `submittedAt`, and `decision`), plus `status`, `headers`, `operation`, `responseStructure`, `inputFormat`, and `resume&#x60; (json)
&#x2A;*`submission`*&#x2A; - Form submission data from the approver (json)
&#x2A;*`resumeInput`*&#x2A; - The raw resume input as received (json)
&#x2A;*`submittedAt`*&#x2A; - ISO timestamp when the workflow was resumed
&#x2A;*`_humanInTheLoopDecision`** - `approved` or `denied&#x60;
&#x2A;*`denied`*&#x2A;, &#x2A;*`error`*&#x2A;, &#x2A;*`rejectionReason`*&#x2A;, &#x2A;*`deniedAt`*&#x2A; - Present only when the decision was denied
&#x2A;*`<fieldName>`** - All fields defined in Resume Form become available at the top level after the workflow resumes

Access using `<blockId.fieldName>`.

## Example

**Paused Output:**

```json
{
  "title": "<agent1.content.title>",
  "body": "<agent1.content.body>",
  "qualityScore": "<evaluator1.score>"
}
```

**Resume Input:**

```json
{
  "approved": { "type": "boolean" },
  "feedback": { "type": "string" }
}
```

**Downstream Usage:**

```javascript
// Condition block
<approval1.approved> === true
```

The example below shows an approval portal as seen by an approver after the workflow is paused. Approvers can review the data and provide inputs as a part of the workflow resumption. The approval portal can be accessed directly via the unique URL, `<blockId.url>`.

[Video: hitl-resume.mp4](https://d4h6f8f5tksdw.cloudfront.net/hitl-resume.mp4)

## Related Blocks

* **[Condition](/blocks/condition)** - Branch based on approval decisions
* **[Variables](/blocks/variables)** - Store approval history and metadata
* **[Response](/blocks/response)** - Return workflow results to API callers

## Common Questions

**How long does the workflow stay paused?**

Without a configured workflow timeout, the pause waits indefinitely for input in SteelEngine, through the approval portal, the REST API, or a webhook. If Execution timeout is set on the workflow, time spent waiting counts toward the original deadline. The run times out when that deadline expires, and resuming does not reset it.

**What notification channels can I use to alert approvers?**

By default the workflow owner, the person who started the run, and any Additional Approvers get an internal notification. They see the approval under 'Waiting on you' on the Notifications page. Switch Notification Type to Internal + External Tools to also send through Slack, Gmail, Microsoft Teams, custom webhooks, or any other integration tool. Switch it to External Tools Only to send through those tools instead. Include the approval URL in your notification message so approvers can access the portal directly.

**How do I deny an approval?**

Use the Deny button on the Notifications page or in the workflow editor. Or send a resume request whose input sets _humanInTheLoopDecision (or decision) to 'denied', optionally with a rejectionReason. The block output gains denied: true, error, rejectionReason, and deniedAt. Execution follows the block's error output handle. If that handle is not connected, the run stops there.

**How do I access the approver's input in downstream blocks?**

Use the syntax <blockId.fieldName> to reference specific fields from the resume form. For example, if your block name is 'approval1' and the form has an 'approved' field, use <approval1.approved>.

**Can I chain multiple Human in the Loop blocks for multi-stage approvals?**

Yes. You can place multiple Human in the Loop blocks in sequence to create multi-stage approval workflows. Each block pauses independently and can have its own notification configuration and resume form fields.

**Can I resume the workflow programmatically without the portal?**

Yes. Each block exposes a resume API endpoint that you can call with a POST request containing the form data as JSON. This lets you build custom approval UIs or integrate with existing systems like Jira or ServiceNow.

**What outputs are available after the workflow resumes?**

The block outputs include the approval portal URL, the resume API endpoint URL, and the full pause response (display data plus submission, submittedAt, and decision). They also include the form submission data, the raw resume input, an ISO timestamp of when the workflow was resumed, and the decision flag _humanInTheLoopDecision. On denial, denied, error, rejectionReason, and deniedAt are added. Resume Form fields are also copied to the top level.
