Executions

An execution is a single invocation of a workflow. Each execution has a unique execution_id — either auto-generated or specified by the caller — and progresses through a sequence of statuses as it runs.

You can start a workflow execution from client code using the Mistral SDK. The workflow_identifier must match the name you passed to @workflows.workflow.define(). If you don't provide an execution_id, the platform generates one automatically.

from mistralai.client import Mistral

client = Mistral(api_key="your_key")

execution = client.workflows.execute_workflow(
    workflow_identifier="my_workflow",
    input={"data": "hello"},
    execution_id="my-run-2024-01-15",  # optional custom ID
)
print(execution.model_dump_json(indent=2))

from mistralai.client import Mistral

client = Mistral(api_key="your_key")

execution = client.workflows.execute_workflow(
    workflow_identifier="my_workflow",
    input={"data": "hello"},
    execution_id="my-run-2024-01-15",  # optional custom ID
)
print(execution.model_dump_json(indent=2))

The returned execution object contains the execution_id and the initial status (typically RUNNING). You can also trigger executions from the Mistral Console or via a schedule.

An execution starts as RUNNING and ends in one of several terminal states:

• COMPLETED — finished successfully
• FAILED — terminated with an unhandled error
• CANCELED — gracefully stopped
• TERMINATED — forcefully stopped
• TIMED_OUT — exceeded execution_timeout
• CONTINUED_AS_NEW — history reset via continue-as-new
• RETRYING_AFTER_ERROR — failed and scheduled for retry

An execution is a workflow invocation with a stable execution_id that persists across its entire lifetime. A run is a single attempt within that execution. Most of the time, an execution has exactly one run. But if a workflow is reset to a previous point in its history, a new run begins under the same execution_id.

Only one run can be active at a time. API action endpoints — /cancel, /terminate, /signals, /queries, /updates — always target the latest run of an execution.