# Python

The official Python SDK for SteelEngine allows you to execute workflows programmatically from your Python applications using the official Python SDK.

The Python SDK supports Python 3.8+ with async execution support, automatic rate limiting with exponential backoff, and usage tracking.

## Installation

Install the SDK using pip:

```bash
pip install steelengine-sdk
```

The distribution is named `steelengine-sdk`. The module you import is `steelengine`.

## Quick Start

Here's a simple example to get you started:

```python
from steelengine import SteelEngineClient

# Initialize the client
client = SteelEngineClient(
    api_key="your-api-key-here",
    base_url="https://steelengine.com"  # optional, defaults to https://steelengine.com
)

# Execute a workflow
try:
    result = client.execute_workflow("workflow-id")
    print("Workflow executed successfully:", result)
except Exception as error:
    print("Workflow execution failed:", error)
```

## API Reference

### SteelEngineClient

#### Constructor

```python
SteelEngineClient(api_key: str, base_url: str = "https://steelengine.com")
```

**Parameters:**

* `api_key` (str): Your SteelEngine API key
* `base_url` (str, optional): Base URL for the SteelEngine API

#### Methods

##### execute\_workflow()

Execute a workflow with optional input data.

```python
result = client.execute_workflow(
    "workflow-id",
    {"message": "Hello, world!"},
    timeout=30.0  # 30 seconds
)
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow to execute
* `input` (any, optional): Input data to pass to the workflow. A dict is sent as the top-level fields of the request body. A string, number, bool, or list is wrapped as `{"input": value}`. The client converts file-like objects inside the input to base64 automatically
* `timeout` (float, optional): Timeout in seconds (default: 30.0)
* `stream` (bool, optional): Request a Server-Sent Events response. The client cannot parse an event stream, so the call fails. See [Streaming Workflow Execution](#streaming-workflow-execution)
* `selected_outputs` (list\[str], optional): Block outputs to stream in `blockName.attribute` format (e.g., `["agent1.content"]`)
* `async_execution` (bool, optional): Send `X-Execution-Mode: async` and return as soon as the run is queued (default: False)
* `use_draft_state` (bool, optional): Execute the draft (unpublished) workflow state. The API rejects this for API-key callers with `400`
* `include_file_base64` (bool, optional): Include base64 file content in outputs (server default: True)
* `base64_max_bytes` (int, optional): Cap on per-file base64 payload size in bytes
* `stop_after_block_id` (str, optional): Stop execution after the given block completes

Every parameter after `input` is keyword-only.

**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`

When `async_execution=True`, returns immediately with a `job_id` for polling. Otherwise, waits for completion.

The client does not model two response shapes. A workflow that ends in a Response block returns the body that block authored. The client reads a `success` field from that body and raises `KeyError` when the field is missing. A synchronous call can also receive HTTP 202 with `pending: true` when the result did not arrive in time. The client returns it as a `WorkflowExecutionResult` with `success=True` and `output=None`, and does not expose the execution ID. Use `requests` directly if you need either shape.

##### execute\_workflow\_sync()

The `timeout` argument controls the client's HTTP request. Set [Execution timeout](/execution#workflow-timeouts) in the workflow menu to limit the run itself, including async runs, waits, and approval pauses. Changing the client timeout does not change that workflow deadline.

Execute a workflow synchronously. `async_execution` is always `False`.

```python
result = client.execute_workflow_sync("workflow-id", {"data": "some input"}, timeout=60.0)
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow to execute
* `input` (any, optional): Input data to pass to the workflow
* `timeout` (float, optional): Timeout in seconds (default: 30.0)
* `stream` (bool, optional): See `execute_workflow()`
* `selected_outputs` (list\[str], optional): Block outputs to stream

**Returns:** `WorkflowExecutionResult`

##### get\_workflow\_status()

Get the status of a workflow (deployment status, etc.).

```python
status = client.get_workflow_status("workflow-id")
print("Is deployed:", status.is_deployed)
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow

**Returns:** `WorkflowStatus`

##### validate\_workflow()

Validate that a workflow is ready for execution.

```python
is_ready = client.validate_workflow("workflow-id")
if is_ready:
    # Workflow is deployed and ready
    pass
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow

**Returns:** `bool`

##### get\_workflow()

Get a workflow's full definition and deployment metadata (`GET /api/workflows/{id}`).

```python
workflow = client.get_workflow("workflow-id")
print("Deployed:", workflow["isDeployed"])
print("Blocks:", list(workflow["state"]["blocks"]))
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow

**Returns:** `Dict[str, Any]` — the workflow record, including `name`, `description`, `workspaceId`, `isDeployed`, `deployedAt`, `variables`, and a `state` object with `blocks`, `edges`, `loops`, `parallels`, and `wireTies` (layout-only wire ties drawn on the canvas)

##### get\_job\_status()

Get the status of an execution by its execution ID.

```python
status = client.get_job_status(result.job_id)
print("Status:", status["status"])  # 'pending', 'processing', 'paused', 'completed', 'failed', 'cancelled'
if status["status"] == "completed":
    print("Output:", status["output"])
```

**Parameters:**

* `task_id` (str): The execution ID returned from async execution (`AsyncExecutionResult.job_id`)

**Returns:** `Dict[str, Any]`

**Response fields:**

* `success` (bool): Whether the lookup was successful
* `jobId` (str): The execution ID
* `taskId` (str): The same value as `jobId`
* `status` (str): One of `'pending'`, `'processing'`, `'paused'`, `'completed'`, `'failed'`, `'cancelled'`. Paused runs are waiting for human input and are not complete
* `metadata` (dict): Contains `workflowId`, `workspaceId`, `userId`, and `executionId`. Once the run has finished, it also contains `startTime`, `endTime`, and `duration`. After the run's execution record expires (7 days after it finishes on SteelEngine Cloud), the status comes from run history and `metadata` holds `workflowId`, `workspaceId`, `executionId`, and `source: "run-history"`
* `output` (any, optional): Present once the run has a result. For an async execution this is the workflow output, or `{"data", "status", "headers"}` when the workflow ended in a Response block. When `metadata["source"]` is `"run-history"`, this is the run-history copy of the output, which is size-capped and has secrets removed
* `error` (str, optional): Error message (when failed or cancelled)
* `startedAt`, `completedAt` (str, optional): ISO 8601 timestamps, present once the result is available. `completedAt` is absent for paused runs
* `executedAt` (str, optional): Same as `completedAt`, present for async executions only

##### cancel\_execution()

Cancel a running or queued execution. Requires write-level access to the workflow.

```python
cancel = client.cancel_execution("workflow-id", result.execution_id)
print("Cancelled:", cancel.success)
```

**Parameters:**

* `workflow_id` (str): The workflow the execution belongs to
* `execution_id` (str): The execution to cancel (`AsyncExecutionResult.execution_id`)

**Returns:** `CancelExecutionResult`

##### execute\_with\_retry()

Execute a workflow with automatic retry on rate limit errors using exponential backoff.

```python
result = client.execute_with_retry(
    "workflow-id",
    {"message": "Hello"},
    timeout=30.0,
    max_retries=3,           # Maximum number of retries
    initial_delay=1.0,       # Initial delay in seconds
    max_delay=30.0,          # Maximum delay in seconds
    backoff_multiplier=2.0   # Exponential backoff multiplier
)
```

**Parameters:**

* `workflow_id` (str): The ID of the workflow to execute
* `input` (any, optional): Input data to pass to the workflow
* `timeout` (float, optional): Timeout in seconds
* `stream` (bool, optional): See `execute_workflow()`
* `selected_outputs` (list, optional): Block outputs to stream
* `async_execution` (bool, optional): Execute asynchronously
* `max_retries` (int, optional): Maximum number of retries (default: 3)
* `initial_delay` (float, optional): Initial delay in seconds (default: 1.0)
* `max_delay` (float, optional): Maximum delay in seconds (default: 30.0)
* `backoff_multiplier` (float, optional): Backoff multiplier (default: 2.0)

Every parameter after `input` is keyword-only.

**Returns:** `WorkflowExecutionResult | AsyncExecutionResult`

The retry logic uses exponential backoff (1s → 2s → 4s → 8s...) with ±25% jitter to prevent thundering herd. If the API provides a `retry-after` header, it will be used instead. The client retries only `RATE_LIMIT_EXCEEDED` errors. It raises every other `SteelEngineError` immediately. To retry any other client call the same way, wrap it in [`with_retry()`](#with_retry).

##### get\_rate\_limit\_info()

Get the rate limit information parsed from the `X-RateLimit-*` and `Retry-After` headers of the last API response.

```python
rate_limit_info = client.get_rate_limit_info()
if rate_limit_info:
    print("Limit:", rate_limit_info.limit)
    print("Remaining:", rate_limit_info.remaining)
```

**Returns:** `RateLimitInfo | None`

The `/api/v1` workflows, logs, and audit logs endpoints send these headers on every response. The other `/api/v1` endpoints send them only with a `429`. The execution, job status, and usage limits endpoints do not send them, so after only those calls this returns `None`. Use `get_usage_limits()` to read your execution rate limit status.

##### get\_usage\_limits()

Get current usage limits and quota information for your account.

```python
limits = client.get_usage_limits()
print("Sync requests remaining:", limits.rate_limit["sync"]["remaining"])
print("Async requests remaining:", limits.rate_limit["async"]["remaining"])
print("Current period cost:", limits.usage["currentPeriodCost"])
print("Plan:", limits.usage["plan"])
print("Storage used:", limits.storage["usedBytes"])
```

**Returns:** `UsageLimits`

**Response structure:**

```python
{
    "success": bool,
    "rateLimit": {
        "sync": {
            "isLimited": bool,
            "requestsPerMinute": int,
            "maxBurst": int,
            "remaining": int,
            "resetAt": str
        },
        "async": {
            "isLimited": bool,
            "requestsPerMinute": int,
            "maxBurst": int,
            "remaining": int,
            "resetAt": str
        },
        "authType": str  # 'api' or 'manual'
    },
    "usage": {
        "currentPeriodCost": float,
        "limit": float,
        "plan": str  # e.g., 'free', 'pro'
    },
    "storage": {
        "usedBytes": int,
        "limitBytes": int,
        "percentUsed": float
    }
}
```

##### list\_workspaces()

List the workspaces the API key has access to (`GET /api/v1/workspaces`).

```python
page = client.list_workspaces(scope="active", limit=50)
for workspace in page["workspaces"]:
    print(workspace["id"], workspace["name"], workspace["roleKey"])
```

**Parameters (keyword-only, optional):**

* `scope` (str): `"active"` (default), `"archived"`, or `"all"`
* `limit` (int): Page size
* `offset` (int): Number of workspaces to skip

**Returns:** `Dict[str, Any]` with `workspaces`, `totalCount`, `limit`, and `offset`

##### create\_workspace()

Create a workspace (`POST /api/v1/workspaces`). Only unscoped personal API keys can create workspaces. Workspace, scoped, and organization keys receive `403`.

```python
workspace = client.create_workspace("Engineering", color="#2563eb")
print("Created:", workspace["id"])
```

**Parameters:**

* `name` (str): Workspace display name
* `color` (str, optional, keyword-only): Workspace color
* `skip_default_workflow` (bool, optional, keyword-only): Don't create the default agent workflow

**Returns:** `Dict[str, Any]` — the created workspace

##### get\_workspace()

Get one workspace (`GET /api/v1/workspaces/{id}`).

```python
workspace = client.get_workspace("workspace-id")
```

**Returns:** `Dict[str, Any]` — the workspace

##### update\_workspace()

Update a workspace (`PATCH /api/v1/workspaces/{id}`). Pass only the fields to change. Requires admin permission on the workspace.

```python
workspace = client.update_workspace("workspace-id", name="Engineering", allow_personal_api_keys=False)
```

**Parameters (keyword-only, optional):**

* `name`, `color` (str)
* `billed_account_user_id` (str): The user billed for this workspace's usage. Must already be an admin on the workspace
* `allow_personal_api_keys` (bool): Whether members can create personal API keys for this workspace

**Returns:** `Dict[str, Any]` — the updated workspace

##### set\_api\_key()

Update the API key.

```python
client.set_api_key("new-api-key")
```

##### set\_base\_url()

Update the base URL.

```python
client.set_base_url("https://my-custom-domain.com")
```

##### close()

Close the underlying HTTP session.

```python
client.close()
```

## Resource Methods

These methods call the `/api/v1` resource endpoints and the human-in-the-loop endpoints. They return the response data as dicts with the API's camelCase keys. Every method raises `SteelEngineError` on failure, with the server's `error` message, `code`, HTTP `status`, and the parsed error `body`. A `429` raises with code `RATE_LIMIT_EXCEEDED`. Path IDs are URL-encoded for you. Arguments after the required IDs are keyword-only. Resource requests time out after 60 seconds.

### Pagination

`list_workflows()`, `query_logs()`, and `list_audit_logs()` return one page as `{"data", "nextCursor", "limits"}`. `nextCursor` is absent or `None` on the last page. Each has an `iter_*()` companion that fetches pages as you read:

```python
for log in client.iter_logs(workspace_id, level="error"):
    print(log["executionId"], log["startedAt"])
```

For any other cursor endpoint, pass a page fetcher to `paginate()`. Set `max_pages` to stop early:

```python
from steelengine import paginate

for log in paginate(lambda cursor: client.query_logs(workspace_id, cursor=cursor), max_pages=5):
    print(log["id"])
```

Table rows and knowledge base documents page with `limit` and `offset` instead.

### with\_retry()

Run any client call with the same rate-limit retry as `execute_with_retry()`: exponential backoff with ±25% jitter, honoring `Retry-After`, retrying only `RATE_LIMIT_EXCEEDED`.

```python
page = client.with_retry(lambda: client.query_logs(workspace_id), max_retries=5)
```

**Parameters:** `call` (a function with no arguments), then keyword-only `max_retries`, `initial_delay`, `max_delay`, and `backoff_multiplier`, with the same defaults as `execute_with_retry()`

### Workflows

| Method                                                                     | Endpoint                     | Returns                                               |
| -------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------- |
| `list_workflows(workspace_id, *, folder_id, deployed_only, limit, cursor)` | `GET /api/v1/workflows`      | One page                                              |
| `iter_workflows(workspace_id, *, max_pages, **filters)`                    | same, every page             | Iterator of workflow summaries                        |
| `get_workflow_metadata(workflow_id)`                                       | `GET /api/v1/workflows/{id}` | Workflow metadata, including `inputs` and `variables` |

`inputs` lists the start block's input fields as `{"name", "type", "description"}` dicts. `get_workflow()` still returns the full block definition from `GET /api/workflows/{id}`.

```python
for workflow in client.iter_workflows(workspace_id, deployed_only=True):
    metadata = client.get_workflow_metadata(workflow["id"])
    print(workflow["name"], metadata.get("inputs"))
```

### Logs

| Method                                             | Endpoint                                    | Returns                                             |
| -------------------------------------------------- | ------------------------------------------- | --------------------------------------------------- |
| `query_logs(workspace_id, **filters)`              | `GET /api/v1/logs`                          | One page                                            |
| `iter_logs(workspace_id, *, max_pages, **filters)` | same, every page                            | Iterator of log entries                             |
| `get_log(log_id)`                                  | `GET /api/v1/logs/{id}`                     | Log detail with trace spans, final output, and cost |
| `get_execution(execution_id)`                      | `GET /api/v1/logs/executions/{executionId}` | Workflow state snapshot and execution metadata      |

`query_logs()` takes the filters of [Query Logs](/api-reference/logs/queryLogs) in snake\_case: `workflow_ids`, `folder_ids`, `triggers`, `level`, `start_date`, `end_date`, `execution_id`, `min_duration_ms`, `max_duration_ms`, `min_cost`, `max_cost`, `model`, `details`, `include_trace_spans`, `include_final_output`, `limit`, `cursor`, and `order`. Pass `workflow_ids`, `folder_ids`, and `triggers` as lists. They are sent comma-separated. `include_trace_spans` and `include_final_output` apply only with `details="full"`.

```python
page = client.query_logs(
    workspace_id,
    triggers=["api", "schedule"],
    level="error",
    start_date="2026-10-01T00:00:00Z",
    limit=50,
)
```

### Audit Logs

| Method                                            | Endpoint                      | Returns                   |
| ------------------------------------------------- | ----------------------------- | ------------------------- |
| `list_audit_logs(**filters)`                      | `GET /api/v1/audit-logs`      | One page                  |
| `iter_audit_logs(*, max_pages, **filters)`        | same, every page              | Iterator of audit entries |
| `get_audit_log(audit_log_id, *, organization_id)` | `GET /api/v1/audit-logs/{id}` | One audit entry           |

Filters: `action`, `resource_type`, `resource_id`, `workspace_id`, `organization_id`, `actor_id`, `start_date`, `end_date`, `include_departed`, and `limit`. A personal API key in more than one organization picks one with `organization_id`, on both list and get.

### Tables

Every table method takes the table's `workspace_id`.

| Method                                                              | Endpoint                          | Returns                                                 |
| ------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------- |
| `list_tables(workspace_id)`                                         | `GET /api/v1/tables`              | `{"tables", "totalCount"}`                              |
| `create_table(workspace_id, name, columns, *, description)`         | `POST /api/v1/tables`             | The table                                               |
| `get_table(table_id, workspace_id)`                                 | `GET /api/v1/tables/{tableId}`    | The table                                               |
| `delete_table(table_id, workspace_id)`                              | `DELETE /api/v1/tables/{tableId}` | `None`                                                  |
| `add_column(table_id, workspace_id, column)`                        | `POST …/columns`                  | The table's columns                                     |
| `update_column(table_id, workspace_id, column_name, updates)`       | `PATCH …/columns`                 | The table's columns                                     |
| `delete_column(table_id, workspace_id, column_name)`                | `DELETE …/columns`                | The table's columns                                     |
| `list_rows(table_id, workspace_id, *, filter, sort, limit, offset)` | `GET …/rows`                      | `{"rows", "rowCount", "totalCount", "limit", "offset"}` |
| `insert_row(table_id, workspace_id, data)`                          | `POST …/rows`                     | The row                                                 |
| `insert_rows(table_id, workspace_id, rows)`                         | `POST …/rows`                     | `{"rows", "insertedCount"}`                             |
| `update_rows(table_id, workspace_id, filter, data, *, limit)`       | `PUT …/rows`                      | `{"message", "updatedCount", "updatedRowIds"}`          |
| `delete_rows(table_id, workspace_id, *, filter, row_ids, limit)`    | `DELETE …/rows`                   | `{"message", "deletedCount", "deletedRowIds"}`          |
| `get_row(table_id, row_id, workspace_id)`                           | `GET …/rows/{rowId}`              | The row                                                 |
| `update_row(table_id, row_id, workspace_id, data)`                  | `PATCH …/rows/{rowId}`            | The row                                                 |
| `delete_row(table_id, row_id, workspace_id)`                        | `DELETE …/rows/{rowId}`           | `None`                                                  |
| `upsert_row(table_id, workspace_id, data, *, conflict_target)`      | `POST …/rows/upsert`              | `{"row", "operation"}`                                  |
| `claim_row(table_id, workspace_id, filter, data)`                   | `POST …/rows/claim`               | `{"id", "original", "row"}` or `None`                   |

Column types are `string`, `number`, `boolean`, `date`, and `json`. `list_rows()` sends `filter` and `sort` as JSON, for example `filter={"age": {"$gt": 18}}` and `sort={"createdAt": "desc"}`. See [List Rows](/api-reference/tables/listRows) for the filter operators. Pass exactly one of `filter` or `row_ids` to `delete_rows()`.

`claim_row()` atomically finds one row that matches an exact-value filter and writes `data` to it, so only one of several competing workers gets each row. At least one filtered field must change. It returns `None` when no row matches:

```python
claim = client.claim_row(table_id, workspace_id, {"status": "queued"}, {"status": "processing"})
if claim:
    process_lead(claim["row"]["data"])
```

### Docs

| Method                                                                 | Endpoint                       | Returns                     |
| ---------------------------------------------------------------------- | ------------------------------ | --------------------------- |
| `list_docs(workspace_id, *, folder_id, scope)`                         | `GET /api/v1/docs`             | `{"docs", "totalCount"}`    |
| `upload_doc(workspace_id, file, *, filename, content_type, folder_id)` | `POST /api/v1/docs`            | The doc's metadata          |
| `download_doc(file_id, workspace_id)`                                  | `GET /api/v1/docs/{fileId}`    | `DownloadedDoc`             |
| `delete_doc(file_id, workspace_id)`                                    | `DELETE /api/v1/docs/{fileId}` | `None`                      |
| `list_doc_folders(workspace_id)`                                       | `GET /api/v1/docs/folders`     | `{"folders", "totalCount"}` |
| `create_doc_folder(workspace_id, name, *, parent_id)`                  | `POST /api/v1/docs/folders`    | The folder                  |

`file` is a path, raw bytes, or a binary file object. Raw bytes need a `filename`. The content type is guessed from the file name unless you pass `content_type`. The SDK sends the file as multipart form data. Docs can be up to 100 MB. `delete_doc()` archives the doc. List with `scope="archived"` to see archived docs.

For doc and knowledge document uploads, a failed request rewinds a seekable file object to its original position so `with_retry()` can resend the same bytes. The SDK leaves caller-owned files open. If a rate-limited upload cannot be rewound, it raises `UPLOAD_NOT_REPLAYABLE` instead of retrying an empty stream; pass a file path, bytes, or a seekable binary file to support retries.

```python
doc = client.upload_doc(workspace_id, "./report.pdf")
download = client.download_doc(doc["id"], workspace_id)
with open(download.filename, "wb") as f:
    f.write(download.content)
```

`DownloadedDoc` has `file_id`, `filename`, `content_type`, and `content` (bytes).

### Knowledge Bases

| Method                                                                                                                     | Endpoint                          | Returns                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------ |
| `list_knowledge_bases(workspace_id)`                                                                                       | `GET /api/v1/knowledge`           | `{"knowledgeBases", "totalCount"}`                                 |
| `create_knowledge_base(workspace_id, name, *, description, chunking_config)`                                               | `POST /api/v1/knowledge`          | The knowledge base                                                 |
| `get_knowledge_base(knowledge_base_id, workspace_id)`                                                                      | `GET /api/v1/knowledge/{id}`      | The knowledge base                                                 |
| `update_knowledge_base(knowledge_base_id, workspace_id, *, name, description, chunking_config)`                            | `PUT /api/v1/knowledge/{id}`      | The knowledge base                                                 |
| `delete_knowledge_base(knowledge_base_id, workspace_id)`                                                                   | `DELETE /api/v1/knowledge/{id}`   | `None`                                                             |
| `list_knowledge_documents(knowledge_base_id, workspace_id, *, limit, offset, search, enabled_filter, sort_by, sort_order)` | `GET …/documents`                 | `{"documents", "pagination"}`                                      |
| `upload_knowledge_document(knowledge_base_id, workspace_id, file, *, filename, content_type)`                              | `POST …/documents`                | The document                                                       |
| `get_knowledge_document(knowledge_base_id, document_id, workspace_id)`                                                     | `GET …/documents/{documentId}`    | The document with its processing status                            |
| `delete_knowledge_document(knowledge_base_id, document_id, workspace_id)`                                                  | `DELETE …/documents/{documentId}` | `None`                                                             |
| `search_knowledge(workspace_id, knowledge_base_ids, *, query, top_k, tag_filters)`                                         | `POST /api/v1/knowledge/search`   | `{"results", "query", "knowledgeBaseIds", "topK", "totalResults"}` |

`update_knowledge_base()` replaces the whole `chunking_config`, so pass all of `maxSize`, `minSize`, and `overlap`.

A document is chunked and embedded after upload. Poll `get_knowledge_document()` until `processingStatus` is `completed` or `failed` before you search it:

```python
import time

doc = client.upload_knowledge_document(kb_id, workspace_id, "./handbook.md")
while doc.get("processingStatus") in ("pending", "processing"):
    time.sleep(2)
    doc = client.get_knowledge_document(kb_id, doc["id"], workspace_id)

results = client.search_knowledge(
    workspace_id, [kb_id], query="How many vacation days do I get?", top_k=5
)["results"]
```

### Human in the Loop

These methods work with runs paused by a [Human in the Loop block](/blocks/human-in-the-loop).

| Method                                                                                        | Endpoint                                                  | Returns                                    |
| --------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------ |
| `list_paused_executions(workflow_id, *, status)`                                              | `GET /api/workflows/{id}/paused`                          | List of paused executions                  |
| `get_paused_execution(workflow_id, execution_id)`                                             | `GET /api/workflows/{id}/paused/{executionId}`            | The paused execution with its pause points |
| `resume_execution(workflow_id, execution_id, context_id, input, *, async_execution, timeout)` | `POST /api/resume/{workflowId}/{executionId}/{contextId}` | The resumed run                            |

`list_paused_executions()` filters on `status`, which defaults to `"paused"`. Pass a list to match several statuses. Each pause point has a `contextId`. Pass it to `resume_execution()` with the human's answer as `input`. Resuming needs write access to the workflow.

`resume_execution()` waits for the resumed run to finish and returns its `output`. The server waits up to 330 seconds, and the client's `timeout` defaults to 360. If the run is still going, the result has a `statusUrl`. With `async_execution=True` it returns at once with a `statusUrl`. Poll it, or call `get_job_status(result.get("jobId") or result["executionId"])`. A result with `"status": "queued"` is waiting behind other resumes of the same run, at `queuePosition`:

```python
paused = client.list_paused_executions(workflow_id)[0]
context_id = paused["pausePoints"][0]["contextId"]

result = client.resume_execution(
    workflow_id,
    paused["executionId"],
    context_id,
    {"approved": True, "comment": "Looks good"},
    async_execution=True,
)
job = client.get_job_status(result.get("jobId") or result["executionId"])
```

## Data Classes

### WorkflowExecutionResult

```python
@dataclass
class WorkflowExecutionResult:
    success: bool
    output: Optional[Any] = None
    error: Optional[str] = None
    logs: Optional[List[Any]] = None
    metadata: Optional[Dict[str, Any]] = None
    trace_spans: Optional[List[Any]] = None
    total_duration: Optional[float] = None
```

The execute endpoint fills `success`, `output`, `error`, and `metadata`. `metadata` holds `startTime`, `endTime`, `duration`, and the version 2 timing fields. `logs`, `trace_spans`, and `total_duration` stay `None`.

### AsyncExecutionResult

```python
@dataclass
class AsyncExecutionResult:
    success: bool
    job_id: str
    execution_id: str
    message: str
    status_url: str
```

`job_id` and `execution_id` carry the same value: the execution ID.

### CancelExecutionResult

```python
@dataclass
class CancelExecutionResult:
    success: bool
    execution_id: str
    durably_recorded: bool
    locally_aborted: bool
    redis_available: bool
    reason: Optional[str] = None
```

### WorkflowStatus

```python
@dataclass
class WorkflowStatus:
    is_deployed: bool
    deployed_at: Optional[str] = None
    needs_redeployment: bool = False
```

### RateLimitInfo

```python
@dataclass
class RateLimitInfo:
    limit: int
    remaining: int
    reset: int                          # Unix time in seconds when the window resets
    retry_after: Optional[int] = None   # milliseconds, from Retry-After
```

### UsageLimits

```python
@dataclass
class UsageLimits:
    success: bool
    rate_limit: Dict[str, Any]
    usage: Dict[str, Any]
    storage: Optional[Dict[str, Any]] = None
```

### SteelEngineError

```python
class SteelEngineError(Exception):
    def __init__(self, message: str, code: Optional[str] = None, status: Optional[int] = None):
        super().__init__(message)
        self.code = code
        self.status = status
        self.body: Optional[Any] = None
```

HTTP errors carry the response `status` (`401`, `402`, `403`, `404`, `409`, `429`, `500`, `503`) and, when the server included one, its `code`. Errors from the [resource methods](#resource-methods) also carry the parsed error `body`. Codes set by the client itself:

* `TIMEOUT`: The request exceeded `timeout`
* `UPLOAD_NOT_REPLAYABLE`: A rate-limited upload could not rewind its file object; retry with a file path, bytes, or a seekable binary file
* `RATE_LIMIT_EXCEEDED`: The API returned `429`
* `EXECUTION_ERROR`: The execute request failed at the transport level
* `STATUS_ERROR`, `CANCEL_ERROR`, `WORKFLOW_ERROR`, `WORKSPACE_ERROR`, `USAGE_ERROR`: The corresponding lookup request failed at the transport level
* `LOGS_ERROR`, `AUDIT_LOG_ERROR`, `TABLE_ERROR`, `DOCS_ERROR`, `KNOWLEDGE_ERROR`, `PAUSED_EXECUTION_ERROR`, `RESUME_ERROR`: A resource method failed at the transport level
* `INVALID_OPTIONS`: A method was called with conflicting or missing arguments, such as `delete_rows()` without `filter` or `row_ids`, or an upload of raw bytes without `filename`
* `PAGINATION_ERROR`: A paginated endpoint returned the same cursor twice
* `MAX_RETRIES_EXCEEDED`: `execute_with_retry()` or `with_retry()` ran out of attempts

Codes passed through from the server include `INVALID_SELECTED_OUTPUT` (`400`) and `RESULT_UNAVAILABLE` (`503`). A `401` response has no code. Check `error.status` instead.

## Examples

### Basic Workflow Execution

**Initialize the client**

Set up the SteelEngineClient with your API key.

**Validate the workflow**

Check if the workflow is deployed and ready for execution.

**Execute the workflow**

Run the workflow with your input data.

**Handle the result**

Process the execution result and handle any errors.

```python
import os
from steelengine import SteelEngineClient

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))

def run_workflow():
    try:
        # Check if workflow is ready
        is_ready = client.validate_workflow("my-workflow-id")
        if not is_ready:
            raise Exception("Workflow is not deployed or ready")

        # Execute the workflow
        result = client.execute_workflow(
            "my-workflow-id",
            {
                "message": "Process this data",
                "user_id": "12345"
            }
        )

        if result.success:
            print("Output:", result.output)
            print("Duration:", result.metadata.get("duration") if result.metadata else None)
        else:
            print("Workflow failed:", result.error)
            
    except Exception as error:
        print("Error:", error)

run_workflow()
```

### Error Handling

Handle different types of errors that may occur during workflow execution:

```python
from steelengine import SteelEngineClient, SteelEngineError
import os

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))

def execute_with_error_handling():
    try:
        result = client.execute_workflow("workflow-id")
        return result
    except SteelEngineError as error:
        if error.status == 401:
            print("Invalid API key")
        elif error.code == "TIMEOUT":
            print("Workflow execution timed out")
        elif error.status == 402:
            print("Usage limit exceeded")
        elif error.code == "RATE_LIMIT_EXCEEDED":
            print("Rate limit exceeded")
        elif error.code == "RESULT_UNAVAILABLE":
            print("Result unavailable; poll the execution instead of resubmitting")
        else:
            print(f"Workflow error: {error}")
        raise
    except Exception as error:
        print(f"Unexpected error: {error}")
        raise
```

### Context Manager Usage

Use the client as a context manager to automatically handle resource cleanup:

```python
from steelengine import SteelEngineClient
import os

# Using context manager to automatically close the session
with SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY")) as client:
    result = client.execute_workflow("workflow-id")
    print("Result:", result)
# Session is automatically closed here
```

### Batch Workflow Execution

Execute multiple workflows efficiently:

```python
from steelengine import SteelEngineClient
import os

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))   

def execute_workflows_batch(workflow_data_pairs):
    """Execute multiple workflows with different input data."""
    results = []
    
    for workflow_id, input_data in workflow_data_pairs:
        try:
            # Validate workflow before execution
            if not client.validate_workflow(workflow_id):
                print(f"Skipping {workflow_id}: not deployed")
                continue
                
            result = client.execute_workflow(workflow_id, input_data)
            results.append({
                "workflow_id": workflow_id,
                "success": result.success,
                "output": result.output,
                "error": result.error
            })
            
        except Exception as error:
            results.append({
                "workflow_id": workflow_id,
                "success": False,
                "error": str(error)
            })
    
    return results

# Example usage
workflows = [
    ("workflow-1", {"type": "analysis", "data": "sample1"}),
    ("workflow-2", {"type": "processing", "data": "sample2"}),
]

results = execute_workflows_batch(workflows)
for result in results:
    print(f"Workflow {result['workflow_id']}: {'Success' if result['success'] else 'Failed'}")
```

### Async Workflow Execution

Execute workflows asynchronously for long-running tasks:

```python
import os
import time
from steelengine import SteelEngineClient, AsyncExecutionResult

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))

def execute_async():
    try:
        # Start async execution
        result = client.execute_workflow(
            "workflow-id",
            {"data": "large dataset"},
            async_execution=True  # Execute asynchronously
        )

        # Check if result is an async execution
        if isinstance(result, AsyncExecutionResult):
            print(f"Job ID: {result.job_id}")
            print(f"Status endpoint: {result.status_url}")

            # Poll for completion
            status = client.get_job_status(result.job_id)

            while status["status"] in ["pending", "processing"]:
                print(f"Current status: {status['status']}")
                time.sleep(2)  # Wait 2 seconds
                status = client.get_job_status(result.job_id)

            if status["status"] == "completed":
                print("Workflow completed!")
                print(f"Output: {status['output']}")
                print(f"Duration: {status['metadata'].get('duration')}")
            elif status["status"] == "paused":
                print("Workflow is waiting for human input")
            else:
                print(f"Workflow {status['status']}: {status.get('error')}")

    except Exception as error:
        print(f"Error: {error}")

execute_async()
```

### Rate Limiting and Retry

Handle rate limits automatically with exponential backoff:

```python
import os
from steelengine import SteelEngineClient, SteelEngineError

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))

def execute_with_retry_handling():
    try:
        # Automatically retries on rate limit
        result = client.execute_with_retry(
            "workflow-id",
            {"message": "Process this"},
            max_retries=5,
            initial_delay=1.0,
            max_delay=60.0,
            backoff_multiplier=2.0
        )

        print(f"Success: {result}")
    except SteelEngineError as error:
        if error.code == "RATE_LIMIT_EXCEEDED":
            print("Rate limit exceeded after all retries")

            # The execute endpoint sends no rate limit headers; read the bucket instead
            limits = client.get_usage_limits()
            print(f"Rate limit resets at: {limits.rate_limit['sync']['resetAt']}")

execute_with_retry_handling()
```

### Usage Monitoring

Monitor your account usage and limits:

```python
import os
from steelengine import SteelEngineClient

client = SteelEngineClient(api_key=os.getenv("STEELENGINE_API_KEY"))

def check_usage():
    try:
        limits = client.get_usage_limits()

        print("=== Rate Limits ===")
        print("Sync requests:")
        print(f"  Per minute: {limits.rate_limit['sync']['requestsPerMinute']}")
        print(f"  Max burst: {limits.rate_limit['sync']['maxBurst']}")
        print(f"  Remaining: {limits.rate_limit['sync']['remaining']}")
        print(f"  Resets at: {limits.rate_limit['sync']['resetAt']}")
        print(f"  Is limited: {limits.rate_limit['sync']['isLimited']}")

        print("\nAsync requests:")
        print(f"  Per minute: {limits.rate_limit['async']['requestsPerMinute']}")
        print(f"  Max burst: {limits.rate_limit['async']['maxBurst']}")
        print(f"  Remaining: {limits.rate_limit['async']['remaining']}")
        print(f"  Resets at: {limits.rate_limit['async']['resetAt']}")
        print(f"  Is limited: {limits.rate_limit['async']['isLimited']}")

        print("\n=== Usage ===")
        print(f"Current period cost: ${limits.usage['currentPeriodCost']:.2f}")
        print(f"Limit: ${limits.usage['limit']:.2f}")
        print(f"Plan: {limits.usage['plan']}")

        percent_used = (limits.usage['currentPeriodCost'] / limits.usage['limit']) * 100
        print(f"Usage: {percent_used:.1f}%")

        if percent_used > 80:
            print("⚠️  Warning: You are approaching your usage limit!")

        print("\n=== Storage ===")
        print(f"Used: {limits.storage['usedBytes']} of {limits.storage['limitBytes']} bytes")
        print(f"Storage: {limits.storage['percentUsed']:.1f}%")

    except Exception as error:
        print(f"Error checking usage: {error}")

check_usage()
```

### Streaming Workflow Execution

The Python SDK has no Server-Sent Events reader. `execute_workflow(stream=True)` sends the request, but the client then tries to parse the event stream as JSON and fails. To stream, call the execute endpoint with `requests` directly:

1. Set `stream` and `selectedOutputs` in the body.
2. Send the `X-SteelEngine-Stream-Version: 2` header.
3. Read the response line by line.

The streaming response follows the Server-Sent Events (SSE) format:

```
data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":"One","outputId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f_content","invocationId":"inv_1"}

data: {"blockId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f","chunk":", two","outputId":"7b7735b9-19e5-4bd6-818b-46aae2596e9f_content","invocationId":"inv_1"}

data: {"event":"done","executionId":"exec_abc123","statusUrl":"https://steelengine.com/api/jobs/exec_abc123","success":true,"status":"success","output":{},"metadata":{"duration":610}}

data: [DONE]
```

Chunks carry `outputId` and `invocationId` so you can tell repeated blocks and several selected fields apart. The stream is complete only when a terminal `done` event arrives, followed by `[DONE]`. A closed connection on its own is not success. An `error` event with `code` `STREAM_INCOMPLETE` or `RESULT_UNAVAILABLE` means you must fetch the result from `statusUrl`. When outputs were selected, a successful `done.output` is `{}` because the values were already delivered.

**Flask Streaming Example:**

```python
from flask import Flask, Response, stream_with_context
import requests
import json
import os

app = Flask(__name__)

@app.route('/stream-workflow')
def stream_workflow():
    """Stream workflow execution to the client."""

    def generate():
        response = requests.post(
            'https://steelengine.com/api/workflows/WORKFLOW_ID/execute',
            headers={
                'Content-Type': 'application/json',
                'X-API-Key': os.getenv('STEELENGINE_API_KEY'),
                'X-SteelEngine-Stream-Version': '2'
            },
            json={
                'message': 'Generate a story',
                'stream': True,
                'selectedOutputs': ['agent1.content']
            },
            stream=True
        )
        response.raise_for_status()
        response.encoding = 'utf-8'

        terminal = None
        for line in response.iter_lines(decode_unicode=True):
            if not line or not line.startswith('data:'):
                continue
            data = line[5:].strip()

            if data == '[DONE]':
                if terminal is None:
                    raise RuntimeError('Stream ended without an execution result')
                yield f"data: {json.dumps(terminal)}\n\n"
                return

            event = json.loads(data)  # Malformed frames are a transport failure, not noise
            if event.get('event') == 'error':
                raise RuntimeError(f"{event.get('code')}: {event.get('error')}")
            if event.get('event') == 'done':
                terminal = event
                continue

            yield f"data: {json.dumps(event)}\n\n"

        raise RuntimeError('Stream closed before its terminal result and [DONE]')

    return Response(
        stream_with_context(generate()),
        mimetype='text/event-stream'
    )

if __name__ == '__main__':
    app.run(debug=True)
```

### Environment Configuration

Configure the client using environment variables:

**Development**

```python
import os
from steelengine import SteelEngineClient

# Development configuration
client = SteelEngineClient(
    api_key=os.getenv("STEELENGINE_API_KEY"),
    base_url=os.getenv("STEELENGINE_BASE_URL", "https://steelengine.com")
)
```

**Production**

```python
import os
from steelengine import SteelEngineClient

# Production configuration with error handling
api_key = os.getenv("STEELENGINE_API_KEY")
if not api_key:
    raise ValueError("STEELENGINE_API_KEY environment variable is required")

client = SteelEngineClient(
    api_key=api_key,
    base_url=os.getenv("STEELENGINE_BASE_URL", "https://steelengine.com")
)
```

## Getting Your API Key

**Log in to SteelEngine**

Navigate to [SteelEngine](https://app.steelengine.com) and log in to your account.

**Open your workflow**

Navigate to the workflow you want to execute programmatically.

**Deploy your workflow**

Click on "Deploy" to deploy your workflow if it hasn't been deployed yet.

**Create or select an API key**

During the deployment process, select or create an API key.

**Copy the API key**

Copy the API key to use in your Python application.

## Requirements

* Python 3.8+
* requests >= 2.25.0

## Common Questions

**Do I need to deploy a workflow before I can execute it via the SDK?**

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 SteelEngine UI first and create or select an API key during deployment.

**What is the difference between sync and async execution?**

Sync execution (the default) blocks until the workflow completes and returns the full result. Async execution (async_execution=True) returns immediately with a job_id, which is the execution ID. Poll it with get_job_status(). Use async mode for long-running workflows to avoid request timeouts. Job statuses are pending, processing, paused, completed, failed, and cancelled. Paused means the run is waiting for human input.

**Can the Python SDK stream block outputs?**

Not through the client. execute_workflow(stream=True) sends the request but cannot parse the Server-Sent Events response. Call the execute endpoint with requests directly, send X-SteelEngine-Stream-Version: 2, and read the stream line by line as shown in Streaming Workflow Execution.

**How does the SDK handle rate limiting?**

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. The execute endpoint does not send rate limit headers, so use get_usage_limits() rather than get_rate_limit_info() to check your current rate limit status.

**Can I use the Python SDK as a context manager?**

Yes. The SteelEngineClient 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.

**How do I handle different types of errors from the SDK?**

The SDK raises SteelEngineError with status and code properties. HTTP failures carry the response status: 401 for an invalid key, 402 for a usage limit, 429 for a rate limit. They also carry any code the server returned, such as RESULT_UNAVAILABLE. The client sets its own codes for TIMEOUT, RATE_LIMIT_EXCEEDED, EXECUTION_ERROR, and MAX_RETRIES_EXCEEDED. Use them to implement targeted error handling and recovery logic.

**How do I monitor my API usage and remaining quota?**

Use the get_usage_limits() method to check your current usage. It returns sync and async rate limit details: requestsPerMinute, maxBurst, remaining, resetAt, and whether you are currently limited. It also returns your current period cost, usage limit, plan tier, and file storage usage. This lets you monitor consumption and alert before hitting limits.
