> ## Documentation Index > Fetch the complete documentation index at: https://docs.hitl.sh/llms.txt > Use this file to discover all available pages before exploring further. # Run a workflow > Starts a run of an active workflow. Answers `202` at once with the execution and a `Location: /v1/api/executions/` header; follow it with [Get a run](/api-reference/runs/get). Needs `workflow:run`. ## OpenAPI ````yaml POST /api/workflows/{id}/run openapi: 3.1.0 info: title: HITL API version: 1.0.0 description: >- Run the workflows you build in HITL, follow each run until a person has answered, and manage who reviews them. servers: - url: https://api.hitl.sh/v1 security: - bearerAuth: [] tags: - name: Workflows - name: Runs - name: Reviewers - name: Webhooks - name: Account - name: Uploads paths: /api/workflows/{id}/run: post: tags: - Runs summary: Run a workflow description: >- Starts a run of an active workflow. Answers `202` at once with the execution and a `Location: /v1/api/executions/` header; follow it with [Get a run](/api-reference/runs/get). Needs `workflow:run`. operationId: runs-run parameters: - name: id in: path required: true description: The workflow id schema: type: string example: 6af2ce4e8207961501f59472 requestBody: required: true content: application/json: schema: type: object properties: input: type: object additionalProperties: true description: >- What the steps read as `{{trigger.body.}}`. Up to 64 KB. callback_url: type: string description: >- Public `https` URL that receives the finished run once (see [Webhooks](/guides/webhooks)) live: type: boolean description: >- Also return a `live` object for watching the run over Statewire example: input: order_id: ORD-48252 customer: name: Mary Jackson email: mary@example.com amount: 320 currency: USD reason: Item never arrived. callback_url: https://example.com/hitl/result responses: '202': description: Accepted content: application/json: schema: type: object properties: error: type: boolean msg: type: string data: $ref: '#/components/schemas/Execution' example: error: false msg: Workflow run started data: id: 6af2da4b2ce04c173fe49697 workflow_id: 6af2ce4e8207961501f59472 workflow_name: Refund approval status: running finished: false input: amount: 320 currency: USD customer: email: mary@example.com name: Mary Jackson order_id: ORD-48252 reason: Item never arrived. decisions: [] action_results: [] triggered_via: api started_at: '2026-11-10T08:48:11.693Z' completed_at: null '400': $ref: '#/components/responses/E400' '401': $ref: '#/components/responses/E401' '403': $ref: '#/components/responses/E403' '404': $ref: '#/components/responses/E404' '409': $ref: '#/components/responses/E409' '429': $ref: '#/components/responses/E429' '503': description: The run could not be queued; it is marked failed. Try again. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Execution: type: object properties: id: type: string workflow_id: type: string workflow_name: type: string status: type: string enum: - running - pending_review - completed - failed - timed_out finished: type: boolean description: True for completed, failed and timed_out input: type: object additionalProperties: true description: What the run was started with current_step: type: object properties: node_id: type: string type: type: string label: type: string waiting_for: type: object description: 'While `pending_review`: the question the reviewers have' properties: request_id: type: string status: type: string request_text: type: string response_type: type: string response_config: type: object additionalProperties: true timeout_at: type: string format: date-time created_at: type: string format: date-time result: description: The last decision, once there is one decisions: type: array items: $ref: '#/components/schemas/Decision' action_results: type: array items: $ref: '#/components/schemas/ActionResult' trail: type: array items: type: object properties: node_id: type: string status: type: string enum: - done - waiting - failed - skipped at: type: string format: date-time error: type: string triggered_via: type: string enum: - api - webhook - email - schedule - manual - test callback_url: type: string callback: type: object properties: state: type: string enum: - queued - delivered - failed attempts: type: integer last_status: type: integer last_error: type: string last_attempt_at: type: string format: date-time delivered_at: type: string format: date-time started_at: type: string format: date-time completed_at: type: - string - 'null' format: date-time duration_seconds: type: number Error: type: object required: - error - msg properties: error: type: boolean example: true msg: type: string description: What went wrong, in plain words code: type: string description: >- A machine-readable reason, when there is one (for example `confirmation_required`) Decision: type: object properties: node_id: type: string description: The review step reviewer_id: type: string reviewer_name: type: string platform: type: string description: 'Where they answered: `mobile`, `web_portal`, `telegram`, ...' decision: description: >- The answer: an option value, a list of values, `true`/`false`, a number or text responded_at: type: string format: date-time response_time_seconds: type: number ActionResult: type: object properties: node_id: type: string type: type: string example: webhook status: type: string enum: - success - failed response: type: string description: Status code and the start of the response executed_at: type: string format: date-time responses: E400: description: Invalid input; `msg` says what to fix content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Invalid execution id E401: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Invalid API key E403: description: The key lacks the scope, or the signup is not confirmed yet content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true code: confirmation_required msg: 'Confirm the signup first: ask your human for the code in the email' E404: description: Not found, or not yours content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Workflow not found E409: description: The workflow is a draft or paused content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: 'Workflow is a draft: publish and activate it in the editor first' status: draft E429: description: 'Rate limit: 1,000 requests an hour per key on /workflows and /executions' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: true msg: Rate limit exceeded securitySchemes: bearerAuth: type: http scheme: bearer description: 'Your API key: `hitl_live_…`' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.