Trigger an agent run from the API

POST /workflows/{workflowId}/run starts an agent run through the August public API. The call is asynchronous: it returns a run_id immediately, and you poll GET /workflows/{workflowId}/runs/{run_id} for status and output.

Before you start

The run operation is protected. August verifies that the caller can access the agent's workflow, including the project it belongs to, and any workflows attached to the run directly or through input bindings.

Send the run request

The operation is POST /workflows/{workflowId}/run, described in the API as "Run an agent".

Send POST /workflows/{workflowId}/run with the request body fields you need (see the table below).
Read the response. It returns run_id, workflow_id, chat_id (or null), and a message of Agent run started or Agent run already existed.
Poll GET /workflows/{workflowId}/runs/{run_id} with the returned run_id until the run finishes.

Request body fields

All fields except the workflow ID are optional. Fields you omit fall back to the agent's saved configuration.

Field	What it does
`projectId`	Project to run in. Defaults to `"personal"`.
`file_ids`, `folder_ids`	Files and folders attached to the run.
`tabular_review_ids`	Tabular reviews attached to the run.
`playbook_ids`	Playbooks attached to the run.
`skill_ids`	Skills attached to the run.
`email_ids`	Emails attached to the run.
`workflow_ids`	Workflows attached to the run.
`workflow_ids_override`	Replaces the agent's default attached workflows.
`run_context`	Context for the run.
`inputs`	Map of input names to string values.
`input_bindings`	Workflow input bindings.
`allow_human_input`	Whether the run may pause for human input. Optional boolean, defaults to `true`.

Use saved defaults or override them

Attachments and the inputs map override the agent's saved defaults. Omit them and the run uses the defaults that GET /workflows/{workflowId}/run-inputs returns.

Run without human input

Set allow_human_input to false to make the run non-interactive. The run cannot ask a person anything: no approval cards are emitted, and the ask-the-user and wait-for-human-input tools are unavailable. The agent proceeds with the attached documents, the provided or default inputs, and the agent definition. Ambiguous or missing values are handled as assumptions and reported rather than blocking the run.

If the run genuinely cannot proceed without human input, it fails with an error of the form Run requires human input that cannot be provided: ... instead of staying paused.

Runs launched from inside August's portal always use this non-interactive behavior and finish with a completion, warning, or failure outcome instead of remaining paused. The interactive path that allow_human_input: false turns off is described in Resume an agent run waiting on human input.

Run outcomes

A run ends in one of three outcomes:

Succeeded. The output contract was satisfied cleanly.
Completed with warnings. The run delivered its output, but something did not go as planned: for example, an input could not be identified, a required item was missing, or a step proceeded on an assumption. Run surfaces show the status "Completed with warnings", and the warning explanation appears in the run details. Review the assumptions or missing inputs before relying on the output.
Failed. Reserved for genuine platform or run-control failures, including a non-interactive run that needed human input it could not get.