shiftlabs Start free
Menu Runs and steps

Runs and steps

A run is one execution of a workflow, on the version that was current when it arrived. Each step runs once and keeps its result, so a run can sleep, wait and resume.

What starts a run

Each run records its origin. Filter by it with GET /v1/runs?origin=, or by Started by on the Runs screen.

  • trigger

    A delivery to a trigger URL. See Deploy and triggers.

  • api · dashboard · mcp

    POST /v1/workflows/:workflow/runs with an API key or shiftlabs run, Run now in the dashboard, or MCP's run_workflow.

  • schedule

    A schedule's tick.

  • workflow

    step.start or step.call in another run.

  • agent

    An agent's workflow tool.

  • rerun

    A re-run of an earlier run, with its version and payload. A payload is kept 14 days, so an older run's re-run gets 410.

origin_ref says who: an email or API key id, the parent run, the schedule's name, or the agent and its conversation. A run stays on the version that was current when it arrived, even after a redeploy or a release.

Statuses

A run is queued, then running or sleeping, until it ends completed, failed, cancelled or terminated.

  • queued

    Not started yet. queued_reason is concurrency while it waits for its workflow's concurrency, or paused while its workflow is paused.

  • running

    Its code is running.

  • sleeping

    Waiting: in a step.sleep, or for an event, an approval or another run. sleeping_until gives a sleep's end.

  • completed

    The function returned. GET /v1/runs/:id shows what it returned as instance.output.

  • failed

    A step ran out of retries, a FatalError was thrown, code outside a step threw, or the run reached a limit. error says why.

  • cancelled · terminated

    Someone stopped it. See Stop a run.

Steps

A step is a named unit of work. step.run runs its function once and stores the result. Each time the run resumes, after a sleep, a wait or a retry, your function starts again from the top: each step returns its stored result, and code outside steps runs again. In the refund-check example, the charge is fetched once, and after the 10-minute sleep the run gets it from storage.

Rules that keep runs correct

  • Put side effects inside steps: requests that change something, and anything that reads the clock or a random number.
  • A resumed run answers each step from storage by its name and how often the run has called that name. Code that calls other steps on a resume runs them again. Test a workflow catches it.
  • state works only inside step.run. See State.
  • step.idempotencyKey(name) is the same on every retry and resume of the run. See Idempotency keys.

Retries and timeouts

A step that throws is tried again, on the same version. Without retries, it gets 5 more tries, 10 seconds apart and doubling. When the tries run out, step.run throws the last error, and uncaught, it fails the run.

  • FatalError

    Fails the step and the run at once, with no more tries.

  • timeout

    An attempt that runs past it fails. Default 10 minutes.

  • Counting

    Retries don't count toward the run's steps. The guide Rate limits and retries retries another API's 429.

Limits on a run

The limits below are the same on Free and Pro unless they say otherwise. See Limits for every value.

  • A run must end within 168 hours of arriving. Past that, it fails, also while it sleeps, with an error that starts limit runLifetimeHours=168.
  • A run executes at most 100 steps on Free and 1,000 on Pro. A step answered from storage, a retry, a sleep or a wait doesn't count.
  • The engine dispatches a run at most 50 times: to start it, and each time it resumes.
  • Each dispatch gets 2,000 ms of CPU time, and a run 10 seconds in all on Free, 60 on Pro.

Follow a run

  • Dashboard

    The Runs screen filters by status, workflow and Started by. A run's page shows its timeline, outbound requests, logs and payload, with Re-run, Cancel run and Terminate run.

  • API

    GET /v1/runs and GET /v1/runs/:id, and each run's /timeline, /logs and /egress. /payload needs a developer key. See API reference.

  • CLI

    shiftlabs runs lists runs, shiftlabs logs <run-id> prints a run's logs, and shiftlabs run <workflow> starts one. See Commands.

  • Kept

    A run is kept 35 days after it ends.

Reference