routinesL4 automation

Workflows that survive a restart.

A routine is a YAML or JSON definition: inputs, triggers and steps that call B3OS products, marketplace actions or other routines. Each publish is an immutable version. Runs pin their version, and after a crash they resume from the journal on the node.

Get API key Read the docs

API: /v1/routines
CLI: b3os routine deploy · b3os routine run · b3os routine logs
MCP tools: routine_*

[01/03] What it does

Familiar syntax

steps with uses, with, needs, if, retry, timeout_ms, map and wait. Expressions are CEL inside ${{ }}, with GitHub-style helpers such as contains, startsWith and toJSON.

PUT /v1/routines/{name}

Triggers

Cron with seconds and a time zone, intervals, signed webhooks and marketplace triggers. Every schedule declares what happens to missed runs.

triggers: [cron, interval, webhook, action]

Durability you choose

ephemeral, standard or strict, per routine or per step. Durable steps commit to a journal on the node's disk before they report done.

defaults.durability

Versions and rollback

Triggers switch to a new version atomically. Rollback moves them back to a version you name, in one call.

POST /v1/routines/{id}/rollback

Runs

Wait for the result in the same request, stream events, send a signal to a waiting step, or cancel.

POST /v1/routines/{id}/runs

A run, step by step

triggercron · nightlysucceeded
pagevision/scrape@1succeeded
summaryinfer/chat@1running
postio.b3os/slack/post-message@1pending

An example run. Each step's state comes from the run's events; durable steps are journaled before they report done.

1name: nightly-digest
2description: Scrape the news page and post a summary
3triggers:
4  - type: cron
5    id: nightly
6    cron: "0 0 6 * * *"
7    tz: America/Los_Angeles
8    catch_up: latest
9steps:
10  - id: page
11    uses: vision/scrape@1
12    with:
13      url: https://news.example.com

name: nightly-digest
description: Scrape the news page and post a summary
triggers:
  - type: cron
    id: nightly
    cron: "0 0 6 * * *"
    tz: America/Los_Angeles
    catch_up: latest
steps:
  - id: page
    uses: vision/scrape@1
    with:
      url: https://news.example.com

1# Publish a version (PUT creates the routine on first deploy)
2curl -sS -X PUT https://beta-api.b3os.org/v1/routines/nightly-digest \
3  -H "Authorization: Bearer $B3OS_API_KEY" \
4  -H "Content-Type: application/yaml" \
5  --data-binary @routine.yaml
6
7# Run it now and wait up to 30 s for the result
8curl -sS "https://beta-api.b3os.org/v1/routines/nightly-digest/runs?wait=30" \
9  -H "Authorization: Bearer $B3OS_API_KEY" \
10  -H "Content-Type: application/json" \
11  -d '{"input":{}}'

# Publish a version (PUT creates the routine on first deploy)
curl -sS -X PUT https://beta-api.b3os.org/v1/routines/nightly-digest \
  -H "Authorization: Bearer $B3OS_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @routine.yaml

# Run it now and wait up to 30 s for the result
curl -sS "https://beta-api.b3os.org/v1/routines/nightly-digest/runs?wait=30" \
  -H "Authorization: Bearer $B3OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{}}'

1import os
2from pathlib import Path
3
4import httpx
5
6api = httpx.Client(
7    base_url="https://beta-api.b3os.org/v1",
8    headers={"Authorization": f"Bearer {os.environ['B3OS_API_KEY']}"},
9    timeout=65,
10)
11
12api.put(
13    "/routines/nightly-digest",
14    content=Path("routine.yaml").read_bytes(),
15    headers={"Content-Type": "application/yaml"},
16).raise_for_status()
17
18run = api.post("/routines/nightly-digest/runs", params={"wait": 30}, json={"input": {}}).json()
19print(run["status"], run.get("result"))

import os
from pathlib import Path

import httpx

api = httpx.Client(
    base_url="https://beta-api.b3os.org/v1",
    headers={"Authorization": f"Bearer {os.environ['B3OS_API_KEY']}"},
    timeout=65,
)

api.put(
    "/routines/nightly-digest",
    content=Path("routine.yaml").read_bytes(),
    headers={"Content-Type": "application/yaml"},
).raise_for_status()

run = api.post("/routines/nightly-digest/runs", params={"wait": 30}, json={"input": {}}).json()
print(run["status"], run.get("result"))

Durable means a run survives process crashes and restarts. It does not survive the loss of the node.
Runs execute as the key that published the version, with the scopes it had then.

[02/03] Measured

What we measure for routines

Values appear here only from published benchmark runs, each with its raw data. A row that says measuring has no published run yet.

Pure step dispatch

Dispatch of steps with no side effects in an ephemeral run, 1 KB payloads.

Measuringp50, server side

Pure step dispatch, p99

The same at the 99th percentile.

Measuringp99, server side

Action call from a step

A routine step calling a pack action in-process, upstream excluded, 1 KB payloads.

Measuringp50, server side

Durable step, standard

An effect step with standard durability, journal commit included.

Measuringp50, server side

Durable step, strict

An effect step with strict durability: an intent commit and a result commit.

Measuringp50, server side

Webhook to first step

From a hook delivery received to the first step started.

Measuringp50, server side

Cron lateness

How late a per-second cron starts its runs: start time minus scheduled time.

Measuringp99, server side

Pure step throughput

Pure steps completed per second across concurrent ephemeral runs.

Measuringthroughput, server side

Durable record throughput

Standard-durability effect records journaled per second, records up to 256 B.

Measuringthroughput, server side

How we measure, and what others publish

[03/03] Beta limits

Free during the beta, with caps

Caps per organization

Routine steps per day: 50,000

Metered units

Routine effect steps: routines.effect_step

Pricing details