feat(api): rename v2 executions to runs

Author: TheodoreSpeaks

apps/docs/content/docs/en/api-reference/(generated)/workflows/meta.json

@@ -8,7 +8,7 @@
     "undeployWorkflow",
     "rollbackWorkflow",
     "executeWorkflowV2",
-    "getWorkflowExecutionV2",
-    "cancelExecutionV2"
+    "getWorkflowRunV2",
+    "cancelRunV2"
   ]
 }

apps/docs/content/docs/en/api-reference/getting-started.mdx

@@ -109,21 +109,23 @@ curl -X POST https://www.sim.ai/api/v2/workflows/{workflowId}/execute \
   -d '{"input": {}, "async": true}'
 ```
 
-This returns immediately with an `executionId` and `statusUrl`:
+Keyed callers can optionally provide `X-Run-Id: my-run-123` to choose the run ID. Run IDs cannot be reused; a duplicate returns `409`.
+
+This returns immediately with a `runId` and `statusUrl`:
 
 ```json
 {
   "data": {
-    "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
-    "statusUrl": "https://www.sim.ai/api/v2/workflows/{workflowId}/executions/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "statusUrl": "https://www.sim.ai/api/v2/workflows/{workflowId}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
   }
 }
 ```
 
-Poll the [Get Execution Status](/api-reference/execution/getWorkflowExecution) endpoint until the status is terminal:
+Poll the run status endpoint until the status is terminal:
 
 ```bash
-curl https://www.sim.ai/api/v2/workflows/{workflowId}/executions/{executionId}?includeOutput=true \
+curl https://www.sim.ai/api/v2/workflows/{workflowId}/runs/{runId}?includeOutput=true \
   -H "X-API-Key: YOUR_API_KEY"
 ```
 
@@ -133,12 +135,12 @@ curl https://www.sim.ai/api/v2/workflows/{workflowId}/executions/{executionId}?i
 
 ## Response Format
 
-Successful v2 responses wrap the execution resource in `data`:
+Successful v2 responses wrap the run resource in `data`:
 
 ```json
 {
   "data": {
-    "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
     "workflowId": "{workflowId}",
     "status": "completed",
     "output": { "result": "Hello, world!" },

apps/docs/content/docs/en/api-reference/python.mdx

@@ -81,7 +81,7 @@ result = client.execute_workflow(
 
 **Returns:** `WorkflowExecutionResult | AsyncExecutionResult`
 
-When `async_execution=True`, returns immediately with an `execution_id` and `status_url` for polling. Otherwise, waits for completion.
+When `async_execution=True`, returns immediately with a `run_id` and `status_url` for polling. Otherwise, waits for completion.
 
 ##### get_workflow_status()
 
@@ -113,27 +113,27 @@ if is_ready:
 
 **Returns:** `bool`
 
-##### get_workflow_execution()
+##### get_workflow_run()
 
 Get the status and optional outputs of a workflow execution.
 
 ```python
-status = client.get_workflow_execution("workflow-id", "execution-id", include_output=True)
+status = client.get_workflow_run("workflow-id", "run-id", include_output=True)
 print("Status:", status["status"])  # 'queued', 'running', 'completed', 'failed'
 if status["status"] == "completed":
     print("Output:", status["output"])
 ```
 
 **Parameters:**
 - `workflow_id` (str): The workflow ID
-- `execution_id` (str): The execution ID returned from async execution
+- `run_id` (str): The run ID returned from async execution
 - `include_output` (bool, optional): Include the final output for completed executions
 - `selected_outputs` (list[str], optional): Block output selectors to include
 
 **Returns:** `Dict[str, Any]`
 
 **Response fields:**
-- `executionId` (str): The execution ID
+- `runId` (str): The run ID
 - `workflowId` (str): The workflow ID
 - `status` (str): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
 - `startedAt` / `endedAt` (str): Execution timestamps
@@ -144,7 +144,7 @@ if status["status"] == "completed":
 
 ##### get_job_status()
 
-Get the status of a job created through the legacy async execution endpoint. New integrations should use `get_workflow_execution()` with the execution ID instead.
+Get the status of a job created through the legacy async execution endpoint. New integrations should use `get_workflow_run()` with the run ID instead.
 
 ```python
 status = client.get_job_status("legacy-job-id")
@@ -283,7 +283,7 @@ class WorkflowExecutionResult:
 @dataclass
 class AsyncExecutionResult:
     success: bool
-    execution_id: str
+    run_id: str
     status_url: str
     message: str = ""
     async_execution: bool = True
@@ -507,19 +507,19 @@ def execute_async():
 
         # Check if result is an async execution
         if hasattr(result, 'async_execution') and result.async_execution:
-            print(f"Execution ID: {result.execution_id}")
+            print(f"Run ID: {result.run_id}")
             print(f"Status endpoint: {result.status_url}")
 
             # Poll for completion
-            status = client.get_workflow_execution(
-                "workflow-id", result.execution_id, include_output=True
+            status = client.get_workflow_run(
+                "workflow-id", result.run_id, include_output=True
             )
 
             while status["status"] in ["queued", "pending", "running"]:
                 print(f"Current status: {status['status']}")
                 time.sleep(2)  # Wait 2 seconds
-                status = client.get_workflow_execution(
-                    "workflow-id", result.execution_id, include_output=True
+                status = client.get_workflow_run(
+                    "workflow-id", result.run_id, include_output=True
                 )
 
             if status["status"] == "completed":
@@ -781,7 +781,7 @@ import { FAQ } from '@/components/ui/faq'
 
 <FAQ items={[
   { question: "Do I need to deploy a workflow before I can execute it via the SDK?", answer: "Yes. Workflows must be deployed before they can be executed through the SDK. You can use the validate_workflow() method to check whether a workflow is deployed and ready. If it returns False, deploy the workflow from the Sim UI first and create or select an API key during deployment." },
-  { question: "What is the difference between sync and async execution?", answer: "Sync execution (the default) blocks until the workflow completes and returns the full result. Async execution (async_execution=True) returns immediately with an execution ID and status URL that you can poll using get_workflow_execution(). Use async mode for long-running workflows to avoid request timeouts. Execution statuses include queued, pending, running, paused, completed, failed, and cancelled." },
+  { question: "What is the difference between sync and async execution?", answer: "Sync execution (the default) blocks until the workflow completes and returns the full result. Async execution (async_execution=True) returns immediately with a run ID and status URL that you can poll using get_workflow_run(). Use async mode for long-running workflows to avoid request timeouts. Run statuses include queued, pending, running, paused, completed, failed, and cancelled." },
   { question: "How does the SDK handle rate limiting?", answer: "The SDK provides built-in rate limiting support through the execute_with_retry() method. It uses exponential backoff (1s, 2s, 4s, 8s...) with 25% jitter to avoid thundering herd problems. If the API returns a retry-after header, that value is used instead. You can configure max_retries, initial_delay, max_delay, and backoff_multiplier. Use get_rate_limit_info() to check your current rate limit status." },
   { question: "Can I use the Python SDK as a context manager?", answer: "Yes. The SimStudioClient supports Python's context manager protocol. Use it with the 'with' statement to automatically close the underlying HTTP session when you are done, which is especially useful for scripts that create and discard client instances." },
   { question: "How do I handle different types of errors from the SDK?", answer: "The SDK raises SimStudioError with a code property for API-specific errors. Common error codes are UNAUTHORIZED (invalid API key), TIMEOUT (request timed out), RATE_LIMIT_EXCEEDED (too many requests), USAGE_LIMIT_EXCEEDED (billing limit reached), and EXECUTION_ERROR (workflow failed). Use the error code to implement targeted error handling and recovery logic." },

apps/docs/content/docs/en/api-reference/typescript.mdx

@@ -95,7 +95,7 @@ const result = await client.executeWorkflow('workflow-id', { message: 'Hello, wo
 
 **Returns:** `Promise<WorkflowExecutionResult | AsyncExecutionResult>`
 
-When `async: true`, returns immediately with an `executionId` and `statusUrl` for polling. Otherwise, waits for completion.
+When `async: true`, returns immediately with a `runId` and `statusUrl` for polling. Otherwise, waits for completion.
 
 ##### getWorkflowStatus()
 
@@ -127,12 +127,12 @@ if (isReady) {
 
 **Returns:** `Promise<boolean>`
 
-##### getWorkflowExecution()
+##### getWorkflowRun()
 
-Get the status and optional outputs of a workflow execution.
+Get the status and optional outputs of a workflow run.
 
 ```typescript
-const status = await client.getWorkflowExecution('workflow-id', 'execution-id', {
+const status = await client.getWorkflowRun('workflow-id', 'run-id', {
   includeOutput: true
 });
 console.log('Status:', status.status); // 'queued', 'running', 'completed', 'failed'
@@ -143,14 +143,14 @@ if (status.status === 'completed') {
 
 **Parameters:**
 - `workflowId` (string): The workflow ID
-- `executionId` (string): The execution ID returned from async execution
+- `runId` (string): The run ID returned from async execution
 - `options.includeOutput` (boolean, optional): Include the final output for completed executions
 - `options.selectedOutputs` (string[], optional): Block output selectors to include
 
-**Returns:** `Promise<WorkflowExecutionStatus>`
+**Returns:** `Promise<WorkflowRunStatus>`
 
 **Response fields:**
-- `executionId` (string): The execution ID
+- `runId` (string): The run ID
 - `workflowId` (string): The workflow ID
 - `status` (string): One of `'queued'`, `'pending'`, `'running'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`
 - `startedAt` / `endedAt` (string): Execution timestamps
@@ -161,7 +161,7 @@ if (status.status === 'completed') {
 
 ##### getJobStatus()
 
-Get the status of a job created through the legacy async execution endpoint. New integrations should use `getWorkflowExecution()` with the execution ID instead.
+Get the status of a job created through the legacy async execution endpoint. New integrations should use `getWorkflowRun()` with the run ID instead.
 
 ```typescript
 const status = await client.getJobStatus('legacy-job-id');
@@ -280,7 +280,7 @@ interface WorkflowExecutionResult {
   logs?: any[];
   metadata?: {
     duration?: number;
-    executionId?: string;
+    runId?: string;
     [key: string]: any;
   };
   traceSpans?: any[];
@@ -293,7 +293,7 @@ interface WorkflowExecutionResult {
 ```typescript
 interface AsyncExecutionResult {
   success: boolean;
-  executionId: string;
+  runId: string;
   statusUrl: string;
   message: string;
   async: true;
@@ -781,18 +781,18 @@ async function executeAsync() {
 
     // Check if result is an async execution
     if ('async' in result && result.async) {
-      console.log('Execution ID:', result.executionId);
+      console.log('Run ID:', result.runId);
       console.log('Status endpoint:', result.statusUrl);
 
       // Poll for completion
-      let status = await client.getWorkflowExecution('workflow-id', result.executionId, {
+      let status = await client.getWorkflowRun('workflow-id', result.runId, {
         includeOutput: true
       });
 
       while (status.status === 'queued' || status.status === 'pending' || status.status === 'running') {
         console.log('Current status:', status.status);
         await new Promise(resolve => setTimeout(resolve, 2000)); // Wait 2 seconds
-        status = await client.getWorkflowExecution('workflow-id', result.executionId, {
+        status = await client.getWorkflowRun('workflow-id', result.runId, {
           includeOutput: true
         });
       }
@@ -1039,7 +1039,7 @@ import { FAQ } from '@/components/ui/faq'
 
 <FAQ items={[
   { question: "Do I need to deploy a workflow before I can execute it via the SDK?", answer: "Yes. Workflows must be deployed before they can be executed through the SDK. You can use the validateWorkflow() method to check whether a workflow is deployed and ready. If it returns false, deploy the workflow from the Sim UI first and create or select an API key during deployment." },
-  { question: "What is the difference between sync and async execution?", answer: "Sync execution (the default) blocks until the workflow completes and returns the full result. Async execution returns immediately with an execution ID and status URL that you can poll using getWorkflowExecution(). Use async mode for long-running workflows to avoid request timeouts. Execution statuses include queued, pending, running, paused, completed, failed, and cancelled." },
+  { question: "What is the difference between sync and async execution?", answer: "Sync execution (the default) blocks until the workflow completes and returns the full result. Async execution returns immediately with a run ID and status URL that you can poll using getWorkflowRun(). Use async mode for long-running workflows to avoid request timeouts. Run statuses include queued, pending, running, paused, completed, failed, and cancelled." },
   { question: "How does streaming work with the SDK?", answer: "Enable streaming by setting stream: true and specifying selectedOutputs with block names and attributes in blockName.attribute format (e.g., ['agent1.content']). The response uses Server-Sent Events (SSE) format, sending incremental chunks as the workflow executes. Each chunk includes the blockId and the text content. A final done event includes the execution metadata." },
   { question: "How does the SDK handle rate limiting?", answer: "The SDK provides built-in rate limiting support through the executeWithRetry() method. It uses exponential backoff (1s, 2s, 4s, 8s...) with 25% jitter to avoid thundering herd problems. If the API returns a retry-after header, that value is used instead. You can configure maxRetries, initialDelay, maxDelay, and backoffMultiplier. Use getRateLimitInfo() to check your current rate limit status." },
   { question: "Is it safe to use the SDK in browser-side code?", answer: "You can use the SDK in the browser, but you should not expose your API key in client-side code. In production, use a backend proxy server to handle SDK calls, or use a public API key with limited permissions. The SDK works with both Node.js and browser environments, but sensitive keys should stay server-side." },

apps/docs/content/docs/en/workflows/blocks/human-in-the-loop.mdx

@@ -87,10 +87,10 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
   <Tab>
     ### REST API
 
-    Programmatically resume workflows through the v2 execution resource. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused execution response.
+    Programmatically resume workflows through the v2 run resource. The `contextId` is available from the block's `resumeEndpoint` output or from the `_resume` object in the paused run response.
 
     ```bash
-    POST /api/v2/workflows/{workflowId}/executions/{executionId}/resume
+    POST /api/v2/workflows/{workflowId}/runs/{runId}/resume
     Content-Type: application/json
     X-API-Key: your-api-key
 
@@ -110,7 +110,7 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
     ```json
     {
       "data": {
-        "executionId": "<resumeExecutionId>",
+        "runId": "<resumeRunId>",
         "workflowId": "<workflowId>",
         "status": "completed",
         "output": { ... },
@@ -126,27 +126,27 @@ Access resume data in downstream blocks using `<blockId.fieldName>`.
 
     - **Stream mode** (`stream: true` on the original execute call) — The resume response streams SSE events with `selectedOutputs` chunks, just like the initial execution.
 
-    - **Async mode** (`async: true` on the original v2 execute call) — The resume dispatches execution to a background worker and returns immediately with `202`, including the resume attempt's `executionId` and v2 `statusUrl` for polling:
+    - **Async mode** (`async: true` on the original v2 execute call) — The resume dispatches the run to a background worker and returns immediately with `202`, including the resume attempt's `runId` and v2 `statusUrl` for polling:
 
     ```json
     {
       "data": {
-        "executionId": "<resumeExecutionId>",
-        "statusUrl": "/api/v2/workflows/<workflowId>/executions/<resumeExecutionId>"
+        "runId": "<resumeRunId>",
+        "statusUrl": "/api/v2/workflows/<workflowId>/runs/<resumeRunId>"
       }
     }
     ```
 
-    #### Polling execution status
+    #### Polling run status
 
     Poll the `statusUrl` from the async response to check when the resume completes:
 
     ```bash
-    GET /api/v2/workflows/{workflowId}/executions/{resumeExecutionId}?includeOutput=true
+    GET /api/v2/workflows/{workflowId}/runs/{resumeRunId}?includeOutput=true
     X-API-Key: your-api-key
     ```
 
-    Returns the execution status and, when completed, the full workflow output.
+    Returns the run status and, when completed, the full workflow output.
 
     The legacy endpoint remains available without behavior changes for existing integrations:
 
@@ -183,7 +183,7 @@ When triggering a workflow through `POST /api/v2/workflows/{id}/execute`, HITL b
     ```json
     {
       "data": {
-        "executionId": "<executionId>",
+        "runId": "<runId>",
         "workflowId": "<workflowId>",
         "status": "paused",
         "output": {

apps/docs/content/docs/en/workflows/deployment/api.mdx

@@ -280,7 +280,7 @@ The `version` field is part of the external API contract. Treat the reference as
 
 ### Asynchronous
 
-For long-running workflows, async mode returns an execution ID immediately so you don't need to hold the connection open. Set `"async": true` in the v2 request body. The API returns HTTP 202 with an execution ID and v2 status URL. Poll that execution resource until the run completes.
+For long-running workflows, async mode returns a run ID immediately so you don't need to hold the connection open. Set `"async": true` in the v2 request body. The API returns HTTP 202 with a run ID and v2 status URL. Poll that run resource until it completes.
 
 To stop an individual async request sooner than the workspace policy, set `executionTimeoutSeconds`
 to an integer from `1` to `604800` (seven days) in the v2 request body. The effective limit is the
@@ -300,23 +300,23 @@ curl -X POST https://sim.ai/api/v2/workflows/{workflow-id}/execute \
 ```json
 {
   "data": {
-    "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
-    "statusUrl": "https://sim.ai/api/v2/workflows/{workflow-id}/executions/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "statusUrl": "https://sim.ai/api/v2/workflows/{workflow-id}/runs/c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74"
   }
 }
 ```
   </Tab>
   <Tab value="Check Status">
 ```bash
-curl "https://sim.ai/api/v2/workflows/{workflow-id}/executions/{executionId}?includeOutput=true" \
+curl "https://sim.ai/api/v2/workflows/{workflow-id}/runs/{runId}?includeOutput=true" \
   -H "x-api-key: $SIM_API_KEY"
 ```
 
 **While processing:**
 ```json
 {
   "data": {
-    "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
     "workflowId": "{workflow-id}",
     "status": "running",
     "startedAt": "2025-09-10T12:00:01.000Z",
@@ -331,7 +331,7 @@ curl "https://sim.ai/api/v2/workflows/{workflow-id}/executions/{executionId}?inc
 ```json
 {
   "data": {
-    "executionId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
+    "runId": "c7a92e15-3f4b-4d8c-a1e6-9b0d5f2c8e74",
     "workflowId": "{workflow-id}",
     "status": "completed",
     "startedAt": "2025-09-10T12:00:01.000Z",