---
title: "Run workflow"
method: POST
path: "/workflow/runs"
tags: ["Workflow"]
---

# Run workflow

`POST /workflow/runs`

## Request

- Base URL: `https://app.amperity.com/api`
- URL: `https://app.amperity.com/api/workflow/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/amperity/apis/amperity-api/docs/workflow/runs/post.ts> (a function with typed inputs; its response is checked against the schema)

Start a workflow. Supports running courier groups, orchestration groups, and campaigns.

## Headers

- `Amperity-Tenant` string, required
- `Api-Version` string, required

## Request body

- WorkflowRunRequest: Fields used to launch a workflow
  - `api_version` string: A [supported version](https://docs.amperity.com/api/versioning.html#supported-versions) of the Amperity API. You may use the `api-version` request header instead of the `api_version` request parameter.
  - `config_id` string, required: The configuration ID of the courier group, orchestration group, or campaign to run. To find it, open the menu in the row for the courier group on the **Sources** page, the orchestration group on the **Destinations** page, or the campaign on the **Campaigns** page, and select **Copy ID**.
  - `range_from` string, date-time: Courier groups only. A timestamp that defines the start (inclusive) of the time window for which couriers pull files. Must be in ISO-8601 format and in UTC. Without `range_to`, couriers pull files for the 24 hours starting at `range_from`, so a date alone selects that day. Required for courier groups that pull files from cloud storage: SFTP, Amazon S3, Azure Blob Storage, or Google Cloud Storage.
  - `range_to` string, date-time: Courier groups only. A timestamp that defines the end (exclusive) of the time window for which couriers pull files. Must be in ISO-8601 format and in UTC. Requires `range_from`; a request with `range_to` alone returns a 400 response.
  - `run_mode` string: Courier groups only. The run mode for the courier group workflow. `full` pulls data, refreshes domain tables, runs Stitch, updates databases, and then runs every activation associated with the workflow, including orchestrations, campaigns, and journeys. `refresh` stops after updating databases. `source` pulls data and refreshes domain tables. Defaults to the run mode configured for the courier group; any other value returns a 400 response.

## Response `201`

Workflow details for newly launched workflow

- Workflow: Representation of a workflow
  - `created_at` string, date-time, required: Time the workflow was created
  - `current_version` string: The current ent version associated with the workflow
  - `ended_at` string, date-time: Time the workflow reached a terminal state
  - `error` WorkflowError: An error on the workflow. Populated only for error states.
    - `attribution` string: The underlying cause of the error, either customer or platform.
    - `data` WorkflowErrorData: Any additional data associated with this error.
    - `message` string, required: The error message.
    - `type` string, required: The type of workflow error.
  - `id` string, required: Unique identifier for the workflow
  - `launched_version` string: The ent version that was launched with the workflow
  - `name` string: Human-readable identifier for the workflow
  - `principal_email` string: Email address for who or what created the workflow
  - `principal_id` string: Principal id for who or what created the workflow
  - `principal_name` string: Human-readable name for who or what created the workflow
  - `state` string, required: Current workflow state.
  - `task_instances` Task[]: The list of tasks on the workflow.
    - `created_at` string, date-time, required: Time the task instance was created
    - `ended_at` string, date-time: Time the task reached a terminal state
    - `error` WorkflowError: An error on the workflow. Populated only for error states.
      - `attribution` string: The underlying cause of the error, either customer or platform.
      - `data` WorkflowErrorData: Any additional data associated with this error.
      - `message` string, required: The error message.
      - `type` string, required: The type of workflow error.
    - `execution_type` string: The execution type for the workflow
    - `id` string, required: Unique identifier for the task instance
    - `label` string, required: Human-readable label for a task-instance
    - `run_id` string: Unique identifier for the task instance to support execution engines that can't provide an external run id
    - `state` string, required: Current task instance state.
    - `state_changed_at` string, date-time: Time the task instance most recently changed state
    - `task_definition_id` string, required: Identifier for a task definition
    - `task_definition_type` string, required: A keyword for identify different task types
    - `tenant` string, required: The unique identifier for the tenant.
    - `timeout_ms` number, double: The length of time in milliseconds after which to forcibly kill a running task instance
    - `workflow_id` string, required: Unique identifier for the workflow
  - `tenant` string, required: The unique identifier for the tenant.
  - `type` string, required: Keyword identifying the type of workflow
  - `warn_after_ms` number, double: The time in milliseconds we should send a running long duration warning

## Other responses

- `400`: Bad Request
- `401`: Authentication Required
- `403`: Not Authorized
- `404`: Not Found
- `405`: Method Not Allowed
- `500`: Internal Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/amperity/apis/amperity-api.md) - [All operations](https://skmtc.dev/amperity/apis/amperity-api/llms.txt) - [OpenAPI document](https://skmtc.dev/amperity/apis/amperity-api/revisions/97ccd051d9dc?raw)