---
id: workflow-execute
title: "Execute a workflow"
description: "Starts an execution of the revision resolved by `alias` (default `latest`) or `revision`. With an `idempotencyKey`, retries return the original execution with 200 and `deduplicated: true`."
sidebar_label: "Execute a workflow"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/workflows
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Execute a workflow"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/workflows/definitions/{id}/execute"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Starts an execution of the revision resolved by `alias` (default `latest`) or `revision`. With an `idempotencyKey`, retries return the original execution with 200 and `deduplicated: true`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"Workflow reference: a server-minted id (`wf_...`) or the workflow's client-chosen key (lowercase slug, unique per organization).","example":"wf_ifWBbWfpug0n"},{"in":"query","name":"alias","schema":{"type":"string"},"description":"Run the revision this alias points at. Defaults to `latest`.","example":"live"},{"in":"query","name":"revision","schema":{"type":"integer"},"description":"Run this revision number instead of an alias."}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"type":"object","description":"Run inputs, matching the workflow's declared inputs.","example":{"due_days":14}},"correlationKey":{"type":"string","description":"Key for targeting this execution with signals later."},"idempotencyKey":{"type":"string","description":"Unique per workflow. Retries with the same key return the original execution."}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An execution with this `idempotencyKey` already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"execution":{"title":"Execution","type":"object","required":["id","workflowId","revision","status","inputs","startedAt","updatedAt"],"properties":{"id":{"type":"string","example":"exec_8f3a1b2c4d5e"},"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"revision":{"type":"integer","example":3},"aliasName":{"type":"string","example":"live"},"organizationId":{"type":"string"},"correlationKey":{"type":"string","description":"Client-chosen key used to target the execution with signals."},"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed","cancelled","timed_out"]},"inputs":{"type":"object","description":"Run inputs. Credential-named keys are masked on reads."},"outputs":{"type":"object"},"variables":{"type":"object"},"error":{"title":"StepError","type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"HTTP_500"},"message":{"type":"string"},"details":{"type":"object"},"retryable":{"type":"boolean"}}},"parentExecutionId":{"type":"string","description":"Present on sub-workflow executions."},"parentStepId":{"type":"string"},"metadata":{"type":"object"},"startedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}},"deduplicated":{"type":"boolean","enum":[true]}}}}}},"202":{"description":"The execution was accepted and started.","content":{"application/json":{"schema":{"type":"object","properties":{"execution":{"title":"Execution","type":"object","required":["id","workflowId","revision","status","inputs","startedAt","updatedAt"],"properties":{"id":{"type":"string","example":"exec_8f3a1b2c4d5e"},"workflowId":{"type":"string","example":"wf_ifWBbWfpug0n"},"revision":{"type":"integer","example":3},"aliasName":{"type":"string","example":"live"},"organizationId":{"type":"string"},"correlationKey":{"type":"string","description":"Client-chosen key used to target the execution with signals."},"idempotencyKey":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed","cancelled","timed_out"]},"inputs":{"type":"object","description":"Run inputs. Credential-named keys are masked on reads."},"outputs":{"type":"object"},"variables":{"type":"object"},"error":{"title":"StepError","type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"HTTP_500"},"message":{"type":"string"},"details":{"type":"object"},"retryable":{"type":"boolean"}}},"parentExecutionId":{"type":"string","description":"Present on sub-workflow executions."},"parentStepId":{"type":"string"},"metadata":{"type":"object"},"startedAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}}}}}}},"4XX":{"description":"Client error. The body says what went wrong: an error `type`, a human-readable `detail`, and, on validation failures, one entry per offending field.","content":{"application/problem+json":{"schema":{"title":"Problem","type":"object","description":"The standard error body (RFC 7807 problem details, served as `application/problem+json`).","properties":{"type":{"type":"string","description":"Error type URI, e.g. `https://workflow-system.dev/errors/workflow-not-found`.","example":"https://workflow-system.dev/errors/workflow-not-found"},"title":{"type":"string","example":"Not found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"No workflow with id wf_ifWBbWfpug0n exists"},"instance":{"type":"string","example":"/workflows/definitions/wf_ifWBbWfpug0n"},"errors":{"type":"array","description":"Present on validation failures: one entry per offending field.","items":{"type":"object","properties":{"path":{"type":"string","example":"/steps/scan/config"},"message":{"type":"string","example":"must have required property 'code'"}}}}}}}}},"5XX":{"description":"Unexpected server error.","content":{"application/problem+json":{"schema":{"title":"Problem","type":"object","description":"The standard error body (RFC 7807 problem details, served as `application/problem+json`).","properties":{"type":{"type":"string","description":"Error type URI, e.g. `https://workflow-system.dev/errors/workflow-not-found`.","example":"https://workflow-system.dev/errors/workflow-not-found"},"title":{"type":"string","example":"Not found"},"status":{"type":"integer","example":404},"detail":{"type":"string","example":"No workflow with id wf_ifWBbWfpug0n exists"},"instance":{"type":"string","example":"/workflows/definitions/wf_ifWBbWfpug0n"},"errors":{"type":"array","description":"Present on validation failures: one entry per offending field.","items":{"type":"object","properties":{"path":{"type":"string","example":"/steps/scan/config"},"message":{"type":"string","example":"must have required property 'code'"}}}}}}}}}}}
>
  
</StatusCodes>