---
title: "Execute workflow version"
method: POST
path: "/agents/v2/workflows/{workflowId}/versions/{versionId}/execute"
tags: ["Workflow Versions"]
---

# Execute workflow version

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

## Request

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

Execute a workflow version by its ID, published or not

## Path parameters

- `workflowId` string, uuid, required
- `versionId` string, uuid, required

## Request body

- WorkflowsVersionExecuteRequest: Request to execute a specific workflow version
  - `agentProfileId` string, uuid
  - `agentProfilePoolId` string, uuid
  - `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.
  - `inputVariables` object: Deprecated: use inputs.
  - `inputs` object: Inputs to be merged into the placeholders defined in prompts. Do not set together with inputVariables.
  - `metadata` object: Optional metadata key-value pairs for organizing and filtering executions
  - `parentExecutionId` string, uuid
  - `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

## Response `202`

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

- WorkflowsVersionExecuteResponse: Response after starting a workflow version execution
  - `executionId` string, uuid, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `500`: Server error

---

[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)