Workflows.

A workflow is an ordered list of steps that runs in a real browser and returns structured data. Author it once — by recording or by describing — then run it on demand, on a schedule, from a webhook, or as a published endpoint and MCP tool.

object ▸ the shape

The workflow object.

A workflow is plain JSON: a name, an ordered steps array, and the declared-input defaults its placeholders resolve against. Each step is a small object with a type and a config.

{
  "name": "Product extractor",
  "description": "Prices from the catalog",
  "workflow_type": "recorded",
  "steps": [
    { "type": "navigate", "config": { "url": "{{url}}" } },
    { "type": "extract",  "config": { "fields": {
        "title": ".product .title",
        "price": ".product .price"
    } } }
  ],
  "form_data": { "url": "https://example.com/catalog" },
  "timeout_ms": 120000,
  "headless": true
}

author ▸ record or describe

Record it, or describe it.

There are two first-class ways to produce that JSON — and a third for sites with a usable API underneath.

steps ▸ the vocabulary

30+ step types.

Steps run in order, and each one can read what earlier steps produced. The vocabulary spans navigation, interaction, waiting, extraction, tabs, AI, authentication and flow control — every type is listed in the step reference with its fields, a real example and its behavior.

Open the step reference →

io ▸ inputs and outputs

Inputs in, structured data out.

A run carries its inputs in the form_data body field. Inside step values, placeholders resolve at run time — so the recipe stays generic and nothing sensitive is stored in it:

On the way out, extract steps fill extracted_data and the run settles with result_data — the structured payload your caller reads.

run ▸ the api

Running a workflow.

One endpoint starts a run. By default the call waits for the verdict; turn wait off to get a task handle back immediately.

POST /api/v1/workflows/{workflow_id}/runs?wait=true&timeout=120
Authorization: Bearer wt_xxxxxxxxxxxx
{ "form_data": { "url": "https://example.com/catalog" } }

# wait=true (default) — the call blocks until the run settles:
{
  "status": "success",
  "success": true,
  "result_data": { "title": "…", "price": "…" },
  "extracted_data": { "title": "…", "price": "…" },
  "error": null,
  "duration_ms": 8412
}

# wait=false — returns immediately with a task handle:
{ "task_id": "…", "status": "pending", "workflow": { "…": "…" } }

From the SDKs

On your own machine, the published SDKs discover the local agent and run the same workflow with no compute charge:

import { WritAgent, runRowId } from "@usewrit/agent-sdk";

const client = new WritAgent();              // discovers the running agent + token
const { data: workflows } = await client.workflows.list();
const run = await client.workflows.runAndWait(workflows[0].id, {
  inputs: { city: "Paris" },
});
const { data: rows } = await client.runs.data(runRowId(run));
console.log(run.status, rows);

from writ_agent import WritAgent, run_row_id

with WritAgent() as client:                  # discovers the local daemon
    run = client.workflows.run_and_wait(3, inputs={"city": "Paris"})
    print(run["status"], run["rows_extracted"])
    print(client.runs.data(run_row_id(run))["data"])   # extracted rows

client, err := writ.Discover(ctx)                        // find the running agent
page, _ := client.Workflows.List(ctx, nil)
item, _ := client.Workflows.RunAndWait(ctx, page.Data[0].ID, nil)
rowID, _ := item.RowID()
csv, _ := client.Runs.DataCSV(ctx, rowID)                // extracted rows as CSV
fmt.Println(item.Status, "
", csv)

use writ_client::{RunOptions, WritAgent};

let agent = WritAgent::discover().await?;                // find the running daemon
let workflows = agent.workflows().list().await?;
let wf = &workflows.data[0];
let outcome = agent.workflows().run_and_wait(wf.id, &RunOptions::default()).await?;
let rows = agent.runs().data(outcome.run.row_id().unwrap()).await?;
println!("{} → {}: {}", wf.name, outcome.run.status, rows.data);

Where a run executes decides what it costs: your local agent runs it for free; a cloud run is metered from your plan’s included usage — see billing.

lifecycle ▸ eight statuses

The run lifecycle.

Every run reports one of eight normalized statuses:

The runs feed unifies five run types in one stream — workflow, check, ai_session, automation and crawl — so everything that executed shows up in one place with the same statuses.

Live events

While a run executes, step-by-step progress streams over SSE — each SDK exposes it in its native idiom:

for await (const ev of client.runs.events(runRowId(run))) {
  console.log(ev.type, ev);
}

for ev in client.runs.events(run_row_id(run)):
    print(ev["type"], ev)

for ev, err := range client.Runs.Events(ctx, rowID) {
    if err != nil { break }
    fmt.Println(ev.Type, ev)
}

use futures_util::StreamExt;
use writ_client::RunEvent;

let mut events = agent.runs().events(run_id).await?;
while let Some(ev) = events.next().await {
    match ev? {
        RunEvent::Step { index, step_type, status, .. } => println!("{index} {step_type} {status}"),
        RunEvent::Finished { status, .. } => println!("done: {status}"),
        _ => {}
    }
}

limits ▸ per plan

How long a run may take.

Every plan sets a maximum run duration. A run that reaches its cap is stopped and settles as failed — it cannot bill open-endedly.

Cloud recording sessions have their own cap: 10 minutes on Free, up to 60 minutes on Scale and Enterprise. Streaming sessions are capped separately — see the streaming reference.

repair ▸ opt-in ai

AI repair.

Sites change. With ai_repair_enabled on a workflow (off by default), a run that breaks on a stale selector triggers repair instead of just failing. Repair works in two tiers:

Repair always runs on the managed cloud AI service and is metered by the tokens it uses — it never runs on a BYO key.

While a workflow is repairing it is locked: other queued runs of the same workflow are held until the repair clears, so they don’t all fail on the same broken step.

Each workflow keeps its last 50 repair entries, each tagged repair_type selector or rerecord — you can audit exactly what was changed and why.

next ▸ where to go

Keep going.

• Step reference — every step type, its fields, and a real example.
• AI sessions — the describe path: goal in, recorded workflow out.
• Managed endpoints — turn this workflow into a REST endpoint; MCP makes it an agent tool.
• Billing & usage — exactly how a cloud run is metered.