---
title: "Execute workflow"
method: POST
path: "/agents/v2/workflows/{workflowId}/execute"
tags: ["Workflows"]
---

# Execute workflow

`POST /agents/v2/workflows/{workflowId}/execute`

## Request

- Base URL: `https://odyssey.asteroid.ai`
- URL: `https://odyssey.asteroid.ai/agents/v2/workflows/{workflowId}/execute`
- Auth: API key in header `X-Api-Key`

Start an execution of the workflow's published version, of the version given in the request, or of the editable head when head is true.

## Path parameters

- `workflowId` string, uuid, required

## Request body

- WorkflowsWorkflowExecuteRequest: Request to execute a workflow
  - `agentProfileId` string, uuid
  - `agentProfilePoolId` string, uuid
  - `dynamicData` object: Deprecated: Use 'inputs' instead. Inputs to be merged into the placeholders defined in prompts
  - `executionOptions` AgentsAgentExecutionOptions: Per-execution runtime options.
    - `softTimeoutMins` integer: Soft timeout in minutes. When the execution has been running longer than this value, a message is injected on every subsequent step urging the agent to wrap up and produce output. Must be greater than 0 and less than the agent's hard timeout (max_timeout_mins).
    - `variantKey` string: Identifies which variant this execution is for, scoping its shared files and scripts to a per-variant subdirectory under each node's shared folder. It does not change which workflow or version runs. Normalised to a filesystem-safe slug by the server. Requires the workflow to have `variant_mode` enabled, and a variant-mode workflow requires it on every execution.
  - `head` boolean: Run the editable head instead of the published version. Cannot be combined with version.
  - `inputs` object: Inputs to be merged into the placeholders defined in prompts
  - `metadata` object: Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions
  - `onCapacityLimit` 'reject' | 'queue': Behaviour when the organisation or profile pool has no capacity for the execution
  - `profileGroupId` string, uuid
  - `profileId` string, uuid
  - `tempFiles` AgentsFilesTempFile[]: Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint
    - `id` string, uuid, required
    - `name` string, required
  - `version` integer: The version of the workflow to execute. If neither version nor head is provided, the published version is used.

## Response `202`

The request has been accepted for processing, but processing has not yet completed.

- WorkflowsWorkflowExecuteResponse: Response after starting a workflow execution
  - `executionId` string, uuid, required
  - `status` 'queued' | 'starting' | 'running' | 'paused' | 'awaiting_confirmation' | 'completed' | 'cancelled' | 'failed' | 'paused_by_agent'

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/asteroid/apis/agent-service.md) - [All operations](https://skmtc.dev/asteroid/apis/agent-service/llms.txt) - [OpenAPI document](https://skmtc.dev/asteroid/apis/agent-service/revisions/ccc134d1d510?raw)