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

# Create a run

> Start one free-form browser task or one ordered workflow.

Requires `runs:write`. Returns `202 Accepted` when the run is durably queued.

<ParamField header="X-Idempotency-Key" type="string">
  Stable mutation key containing 1–255 printable ASCII characters without spaces. Strongly recommended.
</ParamField>

<ParamField body="task" type="string">
  Free-form browser goal. Required when `workflow` is omitted. Maximum 20,000 characters.
</ParamField>

<ParamField body="workflow" type="object">
  Version 1 ordered workflow. Required when `task` is omitted. Maximum 100 steps and 128 KB.
</ParamField>

<ParamField body="metadata" type="object">
  Application-defined correlation metadata. Maximum 16 KB. Defaults to an empty object.
</ParamField>

<Warning>
  Supply exactly one of `task` or `workflow`. Do not place secrets in the task, resolved workflow, or metadata.
</Warning>

## Response

<ResponseField name="id" type="uuid" required>
  Durable run identifier.
</ResponseField>

<ResponseField name="status" type="string" required>
  Usually `queued` or `running` on acceptance.
</ResponseField>

<ResponseField name="runtime" type="string" required>
  `modal` for public cloud runs.
</ResponseField>

<Tip>
  Poll [Get a run](/reference/runs/get) or use an SDK `wait` helper until the run is terminal.
</Tip>


## Related topics

- [Create an API key](/reference/api-keys/create.md)
- [Quickstart](/get-started/quickstart.md)
- [Browser tasks](/guides/browser-tasks.md)
- [API overview](/reference/overview.md)
- [Python SDK](/sdks/python.md)