> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt > Use this file to discover all available pages before exploring further. # Execute workflow > Start an execution of the workflow's published version, or of the version given in the request. ## OpenAPI ````yaml https://odyssey.asteroid.ai/agents/v2/openapi.yaml post /workflows/{workflowId}/execute openapi: 3.1.0 info: title: Agent Service version: v1 servers: - description: V2 API url: https://odyssey.asteroid.ai/agents/v2 security: - ApiKeyAuth: [] tags: - name: Agents - name: Environments - name: Schedules - name: Execution - name: Files - name: Agent Profiles - name: Agent Profile Pools - name: Workflows - name: Execution Batches - name: Scheduled Executions - name: Schema - name: Documentation - name: Context - name: Admin Customer Activity - name: Reference - name: Workflow Tags - name: Vault - name: Workflow Versions paths: /workflows/{workflowId}/execute: post: tags: - Workflows summary: Execute workflow description: >- Start an execution of the workflow's published version, or of the version given in the request. operationId: WorkflowExecutePost parameters: - description: The ID of the workflow to execute in: path name: workflowId required: true schema: $ref: '#/components/schemas/Common.uuid' requestBody: content: application/json: schema: $ref: '#/components/schemas/Workflows.Workflow.ExecuteRequest' description: Execution request parameters required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/Workflows.Workflow.ExecuteResponse' description: >- The request has been accepted for processing, but processing has not yet completed. default: content: application/json: schema: $ref: '#/components/schemas/Common.Error' description: An unexpected error response. components: schemas: Common.uuid: format: uuid type: string Workflows.Workflow.ExecuteRequest: description: Request to execute a workflow properties: agentProfileId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The ID of the agent profile to use for this execution. Mutually exclusive with agentProfilePoolId. agentProfilePoolId: allOf: - $ref: '#/components/schemas/Common.uuid' description: >- The ID of the agent profile pool to select a profile from. Mutually exclusive with agentProfileId. dynamicData: deprecated: true description: >- Deprecated: Use 'inputs' instead. Inputs to be merged into the placeholders defined in prompts type: object unevaluatedProperties: {} x-hidden: true executionOptions: allOf: - $ref: '#/components/schemas/Agents.Agent.ExecutionOptions' description: >- Per-execution runtime options that override or extend the workflow's default settings. inputs: description: Inputs to be merged into the placeholders defined in prompts type: object unevaluatedProperties: {} metadata: description: >- Optional metadata key-value pairs (string keys and string values) for organizing and filtering executions type: object unevaluatedProperties: type: string onCapacityLimit: allOf: - $ref: '#/components/schemas/Agents.Agent.OnCapacityLimit' description: >- What to do when the execution cannot start right now because the organisation is at its concurrency limit or every profile in the pool is in use. "reject" (the default) fails the request as today. "queue" accepts it: the execution is created in the "queued" status under the returned ID and starts automatically, oldest first, as capacity frees. Temp files cannot be queued. tempFiles: description: >- Array of temporary files to attach to the execution. Must have been pre-uploaded using the stage file endpoint items: $ref: '#/components/schemas/Agents.Files.TempFile' type: array version: description: >- The version of the workflow to execute. If not provided, the published version is used. type: integer type: object Workflows.Workflow.ExecuteResponse: description: Response after starting a workflow execution properties: executionId: allOf: - $ref: '#/components/schemas/Common.uuid' description: The ID of the newly created execution status: allOf: - $ref: '#/components/schemas/Agents.Execution.Status' description: >- The execution's initial status: "starting" when it began immediately, "queued" when it is waiting for capacity (only with onCapacityLimit: "queue"). Poll the execution by ID to follow it either way. required: - executionId type: object Common.Error: properties: code: format: int32 type: integer message: type: string required: - code - message type: object Agents.Agent.ExecutionOptions: description: Per-execution runtime options. properties: softTimeoutMins: description: >- 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). minimum: 1 type: integer variantKey: description: >- 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. type: string type: object Agents.Agent.OnCapacityLimit: description: >- Behaviour when the organisation or profile pool has no capacity for the execution enum: - reject - queue type: string Agents.Files.TempFile: properties: id: $ref: '#/components/schemas/Common.uuid' name: type: string required: - id - name type: object Agents.Execution.Status: enum: - queued - starting - running - paused - awaiting_confirmation - completed - cancelled - failed - paused_by_agent type: string securitySchemes: ApiKeyAuth: in: header name: X-Api-Key type: apiKey ````