> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Request human input

> Pause automation and request one bounded response from a person.

Pause automation while a person provides one response. `human.request` is
asynchronous only: it returns a ToolCall that remains in `requires_input` until
the response is submitted or the request expires.

## Request a response

```ts
const call = await bctrl.tools.start("human.request", {
  prompt: "Please confirm the account email before continuing.",
  responseSchema: {
    type: "object",
    properties: { confirmed: { type: "boolean" } },
    required: ["confirmed"],
  },
  expiresInSeconds: 1800,
}, { runtimeId: runtime.id });

console.log(call.id, call.status);
```

The Runtime must be active. Human input can be used with browser, desktop, and
spreadsheet Runtime types.

## Request parameters

| Parameter          | Type         | Required | Description                                                               |
| ------------------ | ------------ | -------- | ------------------------------------------------------------------------- |
| `prompt`           | `string`     | Yes      | Question or instruction shown to the person, from 1 to 10,000 characters. |
| `responseSchema`   | `JsonObject` | No       | JSON Schema that constrains the response.                                 |
| `expiresInSeconds` | `integer`    | No       | Response deadline. Defaults to `1800`; maximum `259200` seconds.          |

## Complete the request

Submit the response with the ToolCall ID, then read the completed result:

```ts
await bctrl.toolCalls.respond(call.id, {
  confirmed: true,
});

const result = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 30,
});

console.log(result);
```

The result is a JSON value: a string, number, boolean, `null`, array, or
object. Cancel an outstanding request with
`bctrl.toolCalls.cancel(call.id)`. An expired or cancelled request does not
produce a human response.

## ToolCall lifecycle

| Status           | Meaning                                |
| ---------------- | -------------------------------------- |
| `queued`         | The request is waiting to run.         |
| `running`        | The request is active.                 |
| `requires_input` | The request is waiting for a response. |
| `succeeded`      | A response was accepted.               |
| `failed`         | The request failed.                    |
| `cancelled`      | The request was cancelled.             |
| `timed_out`      | The request exceeded its allowed time. |

## Next

* [Views](/sdk/views) — give a person a live surface for automation
* [Tools](/sdk/tools) — understand ToolCalls and Toolsets
* [Runs](/sdk/runs) — inspect the execution record