Skip to main content

Executions

Executions are individual runs of a workflow. Use this resource to inspect run status, per-node spans, logs, and progress, and to pause, resume, or cancel a run.

Access it as client.executions on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Quick start​

from strongly import Strongly

client = Strongly()

# List (auto-paginates as you iterate) # filters: workflow_id, search, status, since, until, trigger_type
for execution in client.executions.list():
print(execution.id)

# Retrieve one by id
item = client.executions.retrieve("<id>")

Methods​

Core​

list​

list(*, workflow_id: str | None = None, search: str | None = None, status: str | None = None, since: str | None = None, until: str | None = None, trigger_type: str | None = None, limit: int | None = None) -> SyncPaginator[ExecutionSummary]

List workflow executions with pagination and filtering: each run's summary.

retrieve returns a run's outputs, inputs and failed nodes; list_spans its steps.

Parameters

  • workflow_id (str | None, optional): One workflow's runs; omitted, the runs of every workflow you can see.
  • search (str | None, optional): Only runs whose trigger type, error message or (an agent run's) transcript contains this text (case insensitive).
  • status (str | None, optional): Filter by execution status: "pending", "running", "completed", "completed_with_gaps", "partial_success", "failed", "stopped", "cancelled", "error" or "timeout".
  • since (str | None, optional): ISO timestamp; only return executions created after this time.
  • until (str | None, optional): ISO timestamp; only return executions created before this time.
  • trigger_type (str | None, optional): Filter by trigger type (e.g. "manual", "api", "schedule").
  • limit (int | None, optional): Maximum number of items to return (default: all matching items).

retrieve​

retrieve(execution_id: str) -> Execution

Get a single execution with full details.

Lifecycle & actions​

stop​

stop(execution_id: str) -> Execution

Stop a running execution; answers the execution.

Raises

  • ConflictError: The run is not "running".

resume​

resume(execution_id: str) -> Execution

Resume a failed execution from its checkpoint.

The workflow must save checkpoints. The run keeps its id and inputs: the nodes it finished are reused, the failed node and the rest run again (a failed Loop or Map runs all its items again).

Parameters

  • execution_id (str): The execution ID.

cancel​

cancel(execution_id: str) -> Execution

Cancel an execution that has not finished (pending, queued or running).

The run is marked "cancelled" at once. Cancelling a run that has already finished changes nothing and returns its final status.

Other​

ai_usage​

ai_usage(execution_id: str) -> ExecutionAiUsage

Get an execution's AI Gateway usage: the model calls made for the run.

In requests and input/output/total tokens, in all and per model. This is the run's token usage. Nodes do not record token counts as metrics; the AI Gateway records every call a run makes.

discard_dead_letter​

discard_dead_letter(dead_letter_id: str, *, notes: str | None = None) -> DeadLetter

Give up on a dead letter: it is never retried. notes say why.

list_dead_letters​

list_dead_letters(*, workflow_id: str | None = None, status: str | None = None) -> SyncPaginator[DeadLetter]

List the runs that could not be submitted (dead letters), newest failure first.

Parameters

  • workflow_id (str | None, optional): One workflow's; omitted, every workflow's you can see.
  • status (str | None, optional): Only entries in this status: pending, retrying, resolved, exhausted or discarded (comma-separated for several).

list_spans​

list_spans(execution_id: str, *, node_id: str | None = None, name: str | None = None, status: str | None = None, slim: bool | None = None, limit: int | None = None) -> SyncPaginator[ExecutionSpan]

List an execution's spans (node-level trace records), oldest first, a page at a time.

Every span the run recorded, a step inside a loop once per iteration (metadata["iteration"], metadata["loop_node_id"]), each with its whole input and output. Which spans a run records is its workflow's tracing level (settings.spanLevel: at error only failed steps and the loops' own spans).

Parameters

  • execution_id (str): The execution ID.
  • node_id (str | None, optional): Only the spans of this node.
  • name (str | None, optional): Only the spans with this exact node name.
  • status (str | None, optional): Only the spans with this status: running, completed, failed or skipped.
  • slim (bool | None, optional): True leaves out the payloads (input, output, config): cheap reads of a large run.
  • limit (int | None, optional): The most spans to return; every one when omitted.

logs​

logs(execution_id: str, *, level: str | None = None, pod_name: str | None = None, search: str | None = None, limit: int | None = None) -> SyncPaginator[ExecutionLog]

List an execution's whole log, newest first, a page at a time.

Every line is kept; lines that share a timestamp keep one order across pages.

Parameters

  • execution_id (str): The execution ID.
  • level (str | None, optional): Only logs of this level (e.g. "error", "info").
  • pod_name (str | None, optional): Only the lines this pod wrote (a line's metadata["pod_name"]: the runner's or a distributed worker's).
  • search (str | None, optional): Only the lines whose message or metadata holds this text (any case).
  • limit (int | None, optional): The most log entries to return; every one when omitted.

notify_input_request​

notify_input_request(execution_id: str, request_id: str) -> HumanRequestNotified

Send a waiting human-input request's notification again.

Parameters

  • execution_id (str): The execution's ID.
  • request_id (str): The human-input request's ID (from pending_inputs).

pending_inputs​

pending_inputs(execution_id: str) -> list[HumanRequest]

List what a running execution waits on from a person.

Each request has type ("input", "feedback" or "checkpoint"), request_id (pass it to submit_input), node_id, and what the request asks: prompt and input_schema (input); prompt, feedback_type, ratingScale, choices, form_fields (feedback); title, description, data, approvers, input_fields (checkpoint).

Parameters

  • execution_id (str): The execution ID.

Returns

  • list[HumanRequest]: The pending requests.

progress​

progress(execution_id: str) -> ExecutionProgress

Get an execution's status and progress.

Answers the run's state at once (it never waits for the run): read it again while is_terminal is False. Once the run finished as completed, completed_with_gaps or partial_success the result carries a per-node outputs preview, and next_action says what to check (for example, which nodes produced nothing). The node counts are the run's own, over its top-level nodes: a loop that failed items counts as a failed node (Execution.failed_nodes names it and the node inside it that failed its items).

retrieve_dead_letter​

retrieve_dead_letter(dead_letter_id: str) -> DeadLetter

Get a dead letter and where its retries stand.

retry_dead_letter​

retry_dead_letter(dead_letter_id: str) -> DeadLetterRetry

Retry a dead letter now, as you.

Returns outcome (resolved, pending, exhausted, reverted or unknown), with the execution_id of the run when it started, or the error.

stats​

stats(workflow_id: str, *, search: str | None = None, status: str | None = None, since: str | None = None, until: str | None = None, trigger_type: str | None = None) -> ExecutionStats

Count one workflow's runs, with the same search and filters as list.

Every run the list holds for you is counted (not a page): in all, by status and by what started it.

Parameters

  • workflow_id (str): The workflow.
  • search, status, since, until, trigger_type (optional): As list takes them.

Returns

  • ExecutionStats: total, by_status and by_trigger_type (most first).

submit_input​

submit_input(execution_id: str, *, request_id: str, data: Any) -> HumanRequestAnswer

Answer a pending request of a running workflow execution.

Wait for Input, Human Feedback and Human Checkpoint nodes pause a run (its status stays "running") until a person answers; list what a run waits on with pending_inputs. The run continues within seconds of the answer. The respondent is the API key's user.

Parameters

  • execution_id (str): The execution ID.

  • request_id (str): The pending request's requestId (from pending_inputs).

  • data (Any): The answer, shaped by the request's type:

    • "input": any JSON value (matching the node's input schema when it has one)
    • "feedback": text -> a string; rating -> a number from 1 to ratingScale; choice -> one of choices; form -> a dict with every required form field
    • "checkpoint": &#123;"decision": "approved" | "rejected", "message": "...", "input": &#123;...&#125;&#125;; only an approver can decide when approvers are set