---
title: "Trigger a workflow run"
method: POST
path: "/workflows/{id}/run"
tags: ["Workflows"]
---

# Trigger a workflow run

`POST /workflows/{id}/run`

## Request

- Base URL: `https://workflow.loopfour.ai/api/v1`
- URL: `https://workflow.loopfour.ai/api/v1/workflows/{id}/run`
- Auth: API key in header `x-api-key`

Manually triggers a workflow run. Returns 200 when the run completes synchronously, or 202 when it is queued.

## Path parameters

- `id` string, required

## Request body

- object
  - `input` object: Input data for the workflow.
  - `idempotencyKey` string: Prevent duplicate runs (24h TTL).
  - `mode` 'async' | 'sync': `async` (default) or `sync`.
  - `maxExecutionTimeMs` number: Max wait time for sync mode (1000-300000ms).
  - `onTimeout` 'return_run_id' | 'throw_error': Sync timeout behavior.
  - `onFailure` 'throw_error' | 'switch_to_async': Sync failure behavior.

## Response `200`

Run completed synchronously or idempotency key matched

- object
  - `success` unknown
  - `data` union
    - WorkflowRunSyncResult: Response when workflow completes synchronously (200)
      - `run_id` string, required
      - `status` string, required
      - `workflow_id` string, required
      - `mode` 'sync', required
      - `output` object, required: Workflow output data
      - `duration_ms` number, required: Execution duration in milliseconds
    - WorkflowRunIdempotencyResult: Response when idempotency key matched an existing run (200)
      - `run_id` string, required
      - `status` string, required
      - `workflow_id` string, required
      - `message` string, required

## Other responses

- `202`: Run queued asynchronously
- `400`: Bad request — invalid parameters or request body.
- `401`: Missing or invalid API key.
- `403`: Forbidden — insufficient permissions for this resource.
- `404`: Resource not found.
- `408`: Request timeout — sync execution exceeded maxExecutionTimeMs.
- `500`: Internal server error.

---

[API](https://skmtc.dev/loopfour/apis/loopfour-workflows-api.md) - [All operations](https://skmtc.dev/loopfour/apis/loopfour-workflows-api/llms.txt) - [OpenAPI document](https://skmtc.dev/loopfour/apis/loopfour-workflows-api/revisions/872822a3af00?raw)