Skip to main content
blobhub.types.workflow.Workflow is the typed module for blobhub.compute.workflow blobs. It does one job: run a definition that is already deployed, follow the run until it ends, and read what it did. Writing and deploying definitions is blobhub-cli’s job.
Workflow(revision) raises TypeMismatch when the revision’s blob is not a workflow blob.

Execute

workflow.execute(reference, *, input_data=None, model=None, models=None, session=None) creates one execution and returns an Execution as soon as it exists, with status creating. It does not wait; wait() does. Where it runs and what it runs are separate. The run lives in a session of the revision you built Workflow over, so that revision must be a draft you can write to; a committed one raises Conflict (revision_not_writable). The definition it runs is the reference, which may name a definition on any revision your credential can read, committed ones included. See Workflow Reference.

The reference

<revision> is default or a revision id, and a blob named by alias needs its organization. Each part is at most 64 characters. A mapping works too, keyed like the API’s workflow object: definition alone; blob, revision and definition; or org, blob, revision and definition. A malformed reference raises ValueError before anything is sent. The platform refuses a definition it cannot resolve with PermissionDenied, and a playground definition named by id with CommandError (invalid_definition_category).

Input data

input_data maps a component alias to a value. Each value reaches the workflow’s data component whose alias port names it and whose persistence is execution. An alias that matches no such component is ignored without an error. A value is a data type value of the component’s own type: a message value for a data.message component, a messages value for data.messages, an integer value for data.integer. The platform requires only an object with a type and never checks it against the component, and the SDK sends values exactly as given, so a mismatch reaches the workflow unnoticed. For the usual data.message input:

Choosing the model

model and models name the model a run’s genai.model providers call. A model is "<vendor>/<model>", or a mapping with only "id" and "settings": {"id": "gemini/gemini-3.1-flash-lite", "settings": {"temperature": 0.2}}.
The entries are sent after input_data’s, the models entries first and the * entry last. input_data cannot use the alias *. Which entry a provider follows, what happens to a model a provider cannot run, and how settings combine are in Choosing a Model per Run. The SDK refuses with TypeError, before anything is sent, when: The platform checks the rest when the run is created. It refuses with CommandError invalid_input_data or invalid_model, and the error’s message lists every problem of that check, joined with ; . The SDK does not expose problems as a field. A refused run creates nothing; see When a run is refused. The model that ran is in the run’s log: each provider’s processor.output event carries it in attributes.model, and run.events({"types": ["processor.output"]}) returns those events. See Which model ran.

Sessions

Every execution belongs to a session. session says which: A session alias is 6 to 42 characters of a–z, 0–9, _ and -, and must not look like an id. A session execute created stays even when creating the execution then fails.

Following a run

run.refresh() reads the record again.

Wait

run.wait(*, timeout=900.0, on_event=None, interval=2.0) polls every interval seconds until the run is completed, failed or stopped, and returns that status.
  • A failed or stopped run is returned, not raised. Check the status.
  • timeout raises WaitTimeout and leaves the run going. Call wait() again to keep following it.
  • The end is the run’s status. wait() reads the execution, not an event stream, so it ends when the platform says the run is over. An execution.ended event adds nothing the status does not already say, and the stream can trail the status by up to a minute, so wait() never reads it. To see that event, read it from the session’s stream.
  • on_event receives each new row of the execution log, as a dict with its id, type, created_at and usually a message. Within one poll rows arrive in id order. A row can become visible up to 60 seconds after the time in its id, so each poll also re-reads the last minute, and a row that lands late is passed when it is found, after rows with larger ids. No row is passed twice, across calls to wait() too. An exception from the callback propagates, and the row it was given counts as delivered.
  • A row can come too late for wait(). After the status turns terminal, wait() makes one last pass over the log and returns without waiting out a settle window. A row a concurrent writer commits after that pass is not passed. It is in the log, so read it with run.events(after=...) at least a minute after the run ended.
  • Without on_event, wait() reads no log at all.
A session closed while the run is going stops it, and wait() returns stopped.

Events

run.events(filter=None, *, after=None) returns the run’s event log, oldest first, following the listing to its end. The log accepts a filter with only types and where; after is an event id, or a boundary built with boundary_id to start at a time. The log holds the run’s own flow.* and processor.* rows. What happened in its session is on the session’s stream.

Stop

run.stop() asks the platform to stop the run, which turns stopping, then stopped. Only a running execution can be stopped: straight after execute() the run is still creating, and stop() raises CommandError (invalid_execution_status). Wait for running first:

When creating a run fails

Creating a session and creating an execution are writes, and the SDK never repeats a write after a failure that may have reached the platform (see Errors and retries). The platform takes no idempotency key, so a repeated create_execution would start a second run. execute() makes up to three requests: it reads the session, creates it when it is absent, then creates the execution. Only the last can start a run. A failure in either session step leaves at most an empty session, which the next call with the same alias finds and reuses. But execute() raises the same classes from every step, so when it raises ServerError, or a NetworkError that is not RequestNotSent, a run may have started. Look before you run it again. With a session alias, that is two reads:
Both read indexes that catch up a moment after a write, so wait a few seconds first. Then an empty list, or a PermissionDenied from get_session for a session that was never created, means nothing ran. A RateLimited or RequestNotSent error means nothing ran, and running it again is safe. Name the session with an alias whenever a second run would matter: a session execute() created for you has an id you never saw.

Errors

See also