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-sdkThe 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 keybase_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 executeinput(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 automaticallytimeout(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 Executionselected_outputs(list[str], optional): Block outputs to stream inblockName.attributeformat (e.g.,["agent1.content"])async_execution(bool, optional): SendX-Execution-Mode: asyncand 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 with400include_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 bytesstop_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 executeinput(any, optional): Input data to pass to the workflowtimeout(float, optional): Timeout in seconds (default: 30.0)stream(bool, optional): Seeexecute_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
passParameters:
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 successfuljobId(str): The execution IDtaskId(str): The same value asjobIdstatus(str): One of'pending','processing','paused','completed','failed','cancelled'. Paused runs are waiting for human input and are not completemetadata(dict): ContainsworkflowId,workspaceId,userId, andexecutionId. Once the run has finished, it also containsstartTime,endTime, andduration. After the run's execution record expires (7 days after it finishes on SteelEngine Cloud), the status comes from run history andmetadataholdsworkflowId,workspaceId,executionId, andsource: "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. Whenmetadata["source"]is"run-history", this is the run-history copy of the output, which is size-capped and has secrets removederror(str, optional): Error message (when failed or cancelled)startedAt,completedAt(str, optional): ISO 8601 timestamps, present once the result is available.completedAtis absent for paused runsexecutedAt(str, optional): Same ascompletedAt, 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 toexecution_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 executeinput(any, optional): Input data to pass to the workflowtimeout(float, optional): Timeout in secondsstream(bool, optional): Seeexecute_workflow()selected_outputs(list, optional): Block outputs to streamasync_execution(bool, optional): Execute asynchronouslymax_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 sizeoffset(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 namecolor(str, optional, keyword-only): Workspace colorskip_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 workspaceallow_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
| 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}.
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 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
| 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 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
| 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.
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:
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.
| 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:
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] = NoneThe 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: strjob_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] = NoneWorkflowStatus
@dataclass
class WorkflowStatus:
is_deployed: bool
deployed_at: Optional[str] = None
needs_redeployment: bool = FalseRateLimitInfo
@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-AfterUsageLimits
@dataclass
class UsageLimits:
success: bool
rate_limit: Dict[str, Any]
usage: Dict[str, Any]
storage: Optional[Dict[str, Any]] = NoneSteelEngineError
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] = NoneHTTP 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 exceededtimeoutUPLOAD_NOT_REPLAYABLE: A rate-limited upload could not rewind its file object; retry with a file path, bytes, or a seekable binary fileRATE_LIMIT_EXCEEDED: The API returned429EXECUTION_ERROR: The execute request failed at the transport levelSTATUS_ERROR,CANCEL_ERROR,WORKFLOW_ERROR,WORKSPACE_ERROR,USAGE_ERROR: The corresponding lookup request failed at the transport levelLOGS_ERROR,AUDIT_LOG_ERROR,TABLE_ERROR,DOCS_ERROR,KNOWLEDGE_ERROR,PAUSED_EXECUTION_ERROR,RESUME_ERROR: A resource method failed at the transport levelINVALID_OPTIONS: A method was called with conflicting or missing arguments, such asdelete_rows()withoutfilterorrow_ids, or an upload of raw bytes withoutfilenamePAGINATION_ERROR: A paginated endpoint returned the same cursor twiceMAX_RETRIES_EXCEEDED:execute_with_retry()orwith_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}")
raiseContext 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 hereBatch 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:
- Set
streamandselectedOutputsin the body. - Send the
X-SteelEngine-Stream-Version: 2header. - 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