> ## Documentation Index
> Fetch the complete documentation index at: https://intunedhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Human in the loop

> Pause a Run to ask for input or hand over the browser, then continue

> [!NOTE]
>
> This feature is in **preview**. The API may change before general availability. To try it out, contact [support@intunedhq.com](mailto:support@intunedhq.com) and we'll enable it for your workspace.

## Overview

Some automations can't finish on their own. A login asks for a one-time code, a CAPTCHA won't solve, or a page needs a judgment call. Human in the loop lets a Run pause, ask for help, and continue with the answer. Usually a person answers, but your own system or an agent can answer through the same links.

The Runtime SDK has two methods for this:

* **`askForInput`** asks a question and waits for a JSON answer, such as a 6-digit code.
* **`handoff`** hands over live control of the Run's browser. Whoever takes over acts in the browser, then presses **Done** to hand it back.

Each call creates an *interaction*: a pending question or handoff with links to answer or cancel it. Use these methods for steps your code can't do on its own. If a step can be retried or automated, keep it in code: every interaction holds a machine while it waits.

## How it works

1. Your code calls `askForInput` or `handoff`. The Run pauses on that line.
2. Intuned creates the interaction and gives it a link. For `askForInput`, the link takes the answer (`inputUrl`). For `handoff`, it opens a page that controls the browser (`handoffUrl`).
3. The link reaches whoever answers, either through the `url` your code passed or from the Run or AuthSession operation result API.
4. They answer or press **Done**. Your code continues with the answer.

If no one answers before the timeout, the method throws. Links stop working once an interaction ends.

## Ask for input

```typescript TypeScript theme={null}
import { askForInput } from "@intuned/runtime/interactions";
import { z } from "zod";

const { code } = await askForInput({
  prompt: "Enter the 6-digit code sent to the account phone",
  schema: z.object({ code: z.string().length(6) }),
  url: "https://example.com/intuned-requests",
  headers: { Authorization: `Bearer ${process.env.REQUESTS_TOKEN}` },
});
await page.fill("#otp", code);
```

```python Python theme={null}
import os

from pydantic import BaseModel
from intuned_runtime.interactions import ask_for_input

class Code(BaseModel):
    code: str

answer = await ask_for_input(
    "Enter the 6-digit code sent to the account phone",
    schema=Code,
    url="https://example.com/intuned-requests",
    headers={"Authorization": f"Bearer {os.environ['REQUESTS_TOKEN']}"},
)
await page.fill("#otp", answer.code)
```

With a `schema`, the answer is validated and typed, and the schema is sent as JSON Schema so whoever answers knows what to submit.

To answer, POST the JSON to the interaction's `inputUrl`:

```bash theme={null}
curl -X POST "$INPUT_URL" -H "Content-Type: application/json" -d '{"code": "123456"}'
```

| Response | Meaning |
| - | - |
| `200` | The Run received the answer. |
| `401` | The link is invalid. |
| `410` | The interaction has ended: it timed out, was answered or canceled, or its Run ended. |
| `502` | The Run couldn't be reached. Try again. |

To cancel the interaction instead of answering it, POST to its `cancelUrl` with no body. `askForInput` throws `InteractionCanceledError`. The responses are the same.

```bash theme={null}
curl -X POST "$CANCEL_URL"
```

## Hand off the browser

```typescript TypeScript theme={null}
import { handoff } from "@intuned/runtime/interactions";

await handoff({
  prompt: "Solve the CAPTCHA, then press Done",
  url: "https://example.com/intuned-requests",
});
await page.waitForURL("**/dashboard");
```

```python Python theme={null}
from intuned_runtime.interactions import handoff

await handoff(
    "Solve the CAPTCHA, then press Done",
    url="https://example.com/intuned-requests",
)
await page.wait_for_url("**/dashboard")
```

The `handoffUrl` opens a page with the live browser, the prompt, a countdown, and **Done** and **Cancel** buttons. **Done** resumes the Run. **Cancel** makes `handoff` throw `InteractionCanceledError`. If your workspace restricts access by IP address, the page opens only from allowed addresses.

> [!NOTE]
>
> `handoff` needs a visible browser. Set `headful` to `true` in Intuned.json. In a headless Run, `handoff` throws `InteractionUnsupportedError`. A Run can have one handoff open at a time.

### Check the page after a handoff

Whoever takes over can navigate, open tabs, or change what's on the page. Don't assume the page is where your code left it:

* Wait for the state you need, such as `page.waitForURL` or a selector, instead of continuing right away.
* Re-find elements after the handoff instead of reusing handles from before it.
* If they may have opened a new tab, pick the page you need from `context.pages()`.

## Deliver the link

**With `url`.** Intuned sends a `POST` to the URL with the headers your code passed, for example an `Authorization` header that your endpoint checks. The URL must be public HTTPS. Redirects aren't followed. Deliveries are retried for up to 5 minutes; if they keep failing, the method throws `InteractionDeliveryError`.

```json theme={null}
{
  "id": "ia_V1StGXR8Z5jdHi6B",
  "type": "input",
  "prompt": "Enter the 6-digit code sent to the account phone",
  "jsonSchema": { "type": "object", "properties": { "code": { "type": "string" } }, "required": ["code"] },
  "inputUrl": "https://app.intuned.io/api/hil/ia_V1StGXR8Z5jdHi6B/resolve?token=…",
  "cancelUrl": "https://app.intuned.io/api/hil/ia_V1StGXR8Z5jdHi6B/cancel?token=…",
  "expiresAt": "2026-10-28T14:15:00.000Z",
  "run": { "runId": "ru_…", "jobRunId": null, "projectId": "…" }
}
```

A `handoff` interaction has `handoffUrl` in place of `inputUrl`, and its `cancelUrl` works like the page's **Cancel** button. Every delivery carries an `x-intuned-interaction-id` header with the interaction id, so you can ignore repeats.

**Without `url`.** While a Run is waiting, the [Run result API](https://intunedhq.com/docs/client-apis/api-reference/projectsruns/run-api--result.md) lists its open interactions in `pendingInteractions`, with the same fields. Poll it from your app, then show the link to whoever answers or answer from your own code. AuthSession create, validate and update operations work the same way: while one is `in_progress`, its result ([create](https://intunedhq.com/docs/client-apis/api-reference/projectsauthsessionscreate/create-authsession--result.md), [validate](https://intunedhq.com/docs/client-apis/api-reference/projectsauthsessionsvalidate/validate-authsession--result.md), [update](https://intunedhq.com/docs/client-apis/api-reference/projectsauthsessionsupdate/update-authsession--result.md)) has the same `pendingInteractions` field.

**From the CLI.** [`intuned platform runs get`](https://intunedhq.com/docs/main/05-references/cli/platform#runs-get) lists a waiting Run's interactions, and [`intuned platform interactions resolve`](https://intunedhq.com/docs/main/05-references/cli/platform#interactions-resolve) answers one: it prompts for the input like a local run, or opens the handoff page. [`intuned platform interactions cancel`](https://intunedhq.com/docs/main/05-references/cli/platform#interactions-cancel) cancels one.

> [!WARNING]
>
> Anyone with an `inputUrl`, `handoffUrl` or `cancelUrl` can answer or cancel the interaction until it ends. Share links only with the people and systems that should answer.

## Timeouts and cost

| Method | Default timeout | Max timeout |
| - | - | - |
| `askForInput` | 15 minutes | 60 minutes |
| `handoff` | 10 minutes | 30 minutes |

While an interaction waits, the Run's own timeout is extended every minute, so an answer can take longer than the Run timeout. Pass `extendRunTimeout: false` (`extend_run_timeout=False` in Python) to keep the Run timeout in force instead.

The machine keeps running while it waits, so waiting time counts as compute time. A waiting Run also occupies a machine that other Runs can't use.

## In the IDE and CLI

Local Runs don't use `url`. The developer answers in the terminal:

* `askForInput` asks for each field when the schema has only string, number, and boolean fields, and asks for JSON otherwise. Press **Esc** to cancel.
* `handoff` asks you to use the browser, then press **Enter** to continue or **Esc** to cancel.
* Interactions are answered one at a time.

## Limitations

* Interactions fail right away with `InteractionUnsupportedError` when nobody can answer in a terminal: agent runs, and CLI runs whose input isn't an interactive terminal.
* When an interaction fails (for example, it times out), the attempt fails and is retried like any other error, which asks again.
* Redeploying a project ends its open interactions.

## Related

* [askForInput, handoff (TypeScript)](https://intunedhq.com/docs/main/05-references/runtime-sdk-typescript/human-in-the-loop.md)
* [ask\_for\_input, handoff (Python)](https://intunedhq.com/docs/main/05-references/runtime-sdk-python/human-in-the-loop.md)
* [Runs (single executions)](https://intunedhq.com/docs/main/02-features/runs-single-executions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.