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:

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:

from steelengine import SteelEngineClient

# Initialize the client
client = SteelEngineClient(
    api_key="your-api-key-here",
    base_url="{{API_URL}}"  # optional, defaults to https://dev.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

SteelEngineClient(api_key: str, base_url: str = "{{API_URL}}")

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.

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
  • 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 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.

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.).

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.

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}).

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.

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.

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.

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().

get_rate_limit_info()

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

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.

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:

{
    "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).

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.

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}).

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.

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.

client.set_api_key("new-api-key")
set_base_url()

Update the base URL.

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

Close the underlying HTTP session.

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:

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:

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.

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

MethodEndpointReturns
list_workflows(workspace_id, *, folder_id, deployed_only, limit, cursor)GET /api/v1/workflowsOne page
iter_workflows(workspace_id, *, max_pages, **filters)same, every pageIterator 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}.

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

MethodEndpointReturns
query_logs(workspace_id, **filters)GET /api/v1/logsOne page
iter_logs(workspace_id, *, max_pages, **filters)same, every pageIterator 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 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".

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

Audit Logs

MethodEndpointReturns
list_audit_logs(**filters)GET /api/v1/audit-logsOne page
iter_audit_logs(*, max_pages, **filters)same, every pageIterator 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.

MethodEndpointReturns
list_tables(workspace_id)GET /api/v1/tables{"tables", "totalCount"}
create_table(workspace_id, name, columns, *, description)POST /api/v1/tablesThe 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 …/columnsThe table's columns
update_column(table_id, workspace_id, column_name, updates)PATCH …/columnsThe table's columns
delete_column(table_id, workspace_id, column_name)DELETE …/columnsThe 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 …/rowsThe 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 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:

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

Docs

MethodEndpointReturns
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/docsThe 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/foldersThe 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.

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

MethodEndpointReturns
list_knowledge_bases(workspace_id)GET /api/v1/knowledge{"knowledgeBases", "totalCount"}
create_knowledge_base(workspace_id, name, *, description, chunking_config)POST /api/v1/knowledgeThe 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 …/documentsThe 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:

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.

MethodEndpointReturns
list_paused_executions(workflow_id, *, status)GET /api/workflows/{id}/pausedList 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:

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

@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

@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

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

WorkflowStatus

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

RateLimitInfo

@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

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

SteelEngineError

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 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

Set up the SteelEngineClient with your API key.

Check if the workflow is deployed and ready for execution.

Run the workflow with your input data.

Process the execution result and handle any errors.

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:

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:

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:

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:

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:

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:

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://dev.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:

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(
            '{{API_URL}}/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:

import os
from steelengine import SteelEngineClient

# Development configuration
client = SteelEngineClient(
    api_key=os.getenv("STEELENGINE_API_KEY"),
    base_url=os.getenv("STEELENGINE_BASE_URL", "{{API_URL}}")
)

Getting Your API Key

Navigate to SteelEngine and log in to your account.

Navigate to the workflow you want to execute programmatically.

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

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

Copy the API key to use in your Python application.

Requirements

  • Python 3.8+
  • requests >= 2.25.0

Common Questions

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.
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.
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.
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.
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.
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.
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.

On this page