---
title: Overview
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Card, Cards } from 'fumadocs-ui/components/card'
import { Image } from '@/components/ui/image'
import { FAQ } from '@/components/ui/faq'

Sim's execution engine brings your workflows to life by processing blocks in the correct order, managing data flow, and handling errors gracefully, so you can understand exactly how workflows run in Sim.

<Callout type="info">
  Every workflow run follows a deterministic path based on your block connections and logic, ensuring predictable and reliable results.
</Callout>

## Documentation Overview

<Cards>
  <Card title="Execution Basics" href="/execution/basics">
    Learn about the fundamental execution flow, block types, and how data flows through your
    workflow
  </Card>

  <Card title="Logging" href="/execution/logging">
    Monitor workflow runs with comprehensive logging and real-time visibility
  </Card>

  <Card title="Cost Calculation" href="/execution/costs">
    Understand how workflow run costs are calculated and optimized
  </Card>

  <Card title="External API" href="/execution/api">
    Access run logs and set up webhooks programmatically via REST API
  </Card>

  <Card title="API Deployment" href="/execution/api-deployment">
    Deploy your workflow as a REST API endpoint with sync, streaming, and async modes
  </Card>

  <Card title="Chat Deployment" href="/execution/chat">
    Deploy your workflow as a conversational chat interface with streaming, file uploads, and voice
  </Card>

</Cards>

## Key Concepts

### Topological Execution
Blocks run in dependency order, similar to how a spreadsheet recalculates cells. The execution engine automatically determines which blocks can run based on completed dependencies.

### Path Tracking
The engine actively tracks run paths through your workflow. Router and Condition blocks dynamically update these paths, ensuring only relevant blocks run.

### Layer-Based Processing
Instead of executing blocks one-by-one, the engine identifies layers of blocks that can run in parallel, optimizing performance for complex workflows.

### Run Context
Each workflow maintains a rich context during a run containing:
- Block outputs and states
- Active run paths
- Loop and parallel iteration tracking
- Environment variables
- Routing decisions


## Deployment Snapshots

API, Chat, Schedule, and Webhook runs use the workflow’s active deployment snapshot. Manual runs from the editor use the current draft canvas state, letting you test changes before deploying. Publish a new deployment whenever you change the canvas so every trigger uses the updated version.

<div className="flex justify-center my-6">
  <Image
    src="/static/execution/deployment-versions.png"
    alt="Deployment versions table"
    width={500}
    height={280}
    className="rounded-xl border border-border shadow-sm"
  />
</div>

### Version History

The **General** tab in the Deploy modal shows a version history table for every deployment. Each row shows the version name, who deployed it, and when.

<div className="flex justify-center">
  <Image
    src="/static/execution/deployment-versions-table.png"
    alt="Version history table with multiple deployment versions"
    width={600}
    height={650}
    className="my-6"
  />
</div>

From the version table you can:

- **Rename** a version to give it a meaningful label (e.g., "v2 — added error handling")
- **Add a description** with notes about what changed in that deployment
- **Promote to live** to roll back to an older version — this makes the selected version the active deployment without changing your draft canvas
- **Load into editor** to restore a previous version's workflow into the canvas for editing and redeploying
- **Preview a version** by selecting a row to view that version's workflow in the canvas preview, then toggle between **Live** and the selected version

<div className="flex justify-center">
  <Image
    src="/static/execution/deployment-version-preview.png"
    alt="Previewing a selected deployment version"
    width={600}
    height={650}
    className="my-6"
  />
</div>

<Callout type="info">
  Promoting an old version takes effect immediately — all API, Chat, Schedule, and Webhook executions will use the promoted version. Your draft canvas is not affected.
</Callout>

## Programmatic Access

Run workflows from your applications using our official SDKs:

```bash
# TypeScript/JavaScript
npm install simstudio-ts-sdk

# Python
pip install simstudio-sdk
```

```typescript
// TypeScript Example
import { SimStudioClient } from 'simstudio-ts-sdk';

const client = new SimStudioClient({ 
  apiKey: 'your-api-key' 
});

const result = await client.executeWorkflow('workflow-id', {
  input: { message: 'Hello' }
});
```

## Best Practices

### Design for Reliability
- Handle errors gracefully with appropriate fallback paths
- Use environment variables for sensitive data
- Add logging to Function blocks for debugging

### Optimize Performance
- Minimize external API calls where possible
- Use parallel execution for independent operations
- Cache results with Memory blocks when appropriate

### Monitor Runs
- Review logs regularly to understand performance patterns
- Track costs for AI model usage
- Use workflow snapshots to debug issues

## What's Next?

Start with [Execution Basics](/execution/basics) to understand how workflows run, then explore [Logging](/execution/logging) to monitor your runs and [Cost Calculation](/execution/costs) to optimize your spending.

<FAQ items={[
  { question: "What are the run timeout limits?", answer: "Synchronous runs (API, chat) have a default timeout of 5 minutes on the Free plan and 50 minutes on Pro, Team, and Enterprise plans. Asynchronous runs (schedules, webhooks) allow up to 90 minutes across all plans. These limits are configurable by the platform administrator." },
  { question: "How does parallel execution work?", answer: "The engine identifies layers of blocks with no dependencies on each other and runs them concurrently. Within loops and parallel blocks, the engine supports up to 20 parallel branches by default and up to 1,000 loop iterations. Nested subflows (loops inside parallels, or vice versa) are supported up to 10 levels deep." },
  { question: "Can I cancel a running workflow?", answer: "Yes. The engine supports cancellation through an abort signal mechanism. When you cancel a run, the engine checks for cancellation between blocks (at roughly 500ms intervals when using Redis-backed cancellation). Any in-progress blocks complete, and the run returns with a cancelled status." },
  { question: "What is a deployment snapshot?", answer: "A deployment snapshot is a frozen copy of your workflow at the time you click Deploy. Trigger-based runs (API, chat, schedule, webhook) use the active snapshot, not your draft canvas. Manual runs from the editor use the current draft canvas state, so you can test changes before deploying. You can view, compare, and roll back snapshots from the Deploy modal." },
  { question: "How are run costs calculated?", answer: "Costs are tracked per block based on the AI model used. Each block log records input tokens, output tokens, and the computed cost using the model's pricing. The total workflow cost is the sum of all block-level costs for that run. You can review costs in the run logs." },
  { question: "What happens when a block fails during a run?", answer: "When a block throws an error, the engine captures the error message in the block log, finalizes any incomplete logs with timing data, and halts the run with a failure status. If the failing block has an error output handle connected to another block, that error path is followed instead of halting entirely." },
  { question: "Can I re-run part of a workflow without starting from scratch?", answer: "Yes. The run-from-block feature lets you select a specific block and re-run from that point. The engine computes which upstream blocks need to be re-run (the dirty set) and preserves cached outputs from blocks that have not changed, so only the affected portion of the workflow re-runs." },
]} />
