Run a saved workflow
writ_run_workflowDestructive
Runs a saved workflow by id or name and, by default, waits for it to finish, returning the extracted data. Workflow inputs go as top-level fields or under inputs; file inputs go under files.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait for completion and return the data (default true). | |
| files | No | Optional file inputs for this run, as {slot: file_id}. Slot names come from the workflow's `file_slots` (writ_list_workflows); file_ids come from the account's file library. An upload step with a pinned file uses it when `files` is omitted; a value here swaps the file for this run only. | |
| device | No | Run on this linked Writ desktop (an agent_id from writ_devices) — overrides the desktop this connection chose with writ_devices action='use'. | |
| inputs | No | Run inputs (top-level fields work too). | |
| output | No | Response shape, for an answer a program or an API consumes rather than a reader. {shape: 'envelope' (default: Writ's full answer, projected) | 'table' ({columns, rows, total}) | 'records' (bare list of records) | 'record' (the newest record alone: one entity, a usage meter, a dashboard), fields: ['used', 'percent_used as pct', 'items.0.price as first_price'] (ordered pick, renames, dotted paths; a missing path is null, so keys are stable), exclude: ['depth'], include_meta: false (page metadata content_kind/depth/thumbnails is stripped unless true), key: 'usage' (wrap)}. On writ_crawl_site with save_as it is saved as the API's default shape. | |
| max_age | No | Optional. Reuse a previous result if it is younger than this many seconds, instead of running the workflow again. 0 (the default) always runs fresh. A reused result answers at once and costs nothing. | |
| workflow | No | Workflow name (or workflow_id). | |
| persona_id | No | Run AS this saved identity (see writ_personas) — the run signs in with the persona's warm session. Omit to use the workflow's default persona, if it has one. A persona of the user's linked DESKTOP (`device:<agent>:<id>`, source='device' in writ_personas) sends the run to that desktop, which signs in from its own vault: the credentials never leave it. | |
| workflow_id | No | A number, or `local:<id>` for a workflow that lives on the user's linked Writ desktop (writ_list_workflows, runs_on='desktop') - it runs there, signed in as one of that desktop's personas when persona_id is `device:...`. | |
| function_name | No | One named function of a multi-function workflow (an API built with writ_website_to_api / writ_browser_compose define_function): only that function and the sign-in functions it depends on run. Omitted, the whole workflow runs. It is a control, never a workflow input. | |
| mutation_mode | No | How a write function (one that creates/posts/sends/deletes) runs on this run. Default 'live': a run is an explicit call, so its writes are sent. 'dry_run' previews the request without sending it; 'private_test' sends it with the function's safe overrides. (Separately, BUILDING a function — define/compile/test — never sends a write, whatever this is.) Reads ignore this. | |
| function_names | No | Several functions in one run, in place of `function_name`: the union of their steps runs once, in recorded order (a prerequisite they share runs once). Not for a desktop (`local:`) workflow. A control, never a workflow input. | |
| timeout_seconds | No | Max seconds to wait for completion (default 120). | |
| use_residential | No | Per-call network override for an owned workflow: true uses the platform residential network, false disables the workflow's residential default. For geo-sensitive sites and sites that block datacenter addresses. | |
| execution_target | No | Where this run executes: 'cloud' (managed fleet), 'auto' (prefer the user's OWN linked Writ desktop app when online, else cloud), or 'local' (require their own desktop app — keeps the run on their machine + IP). Omit to keep the workflow's own configured target. A 'local' run fails while that desktop app is offline; 'cloud' runs the same workflow on Writ's fleet, off the user's machine and IP. | |
| residential_country | No | Two-letter ISO-3166 exit country for this call (for example ca, us, fr). Keep it aligned with the requested storefront, coordinates or delivery market. It is applied when the run uses residential egress. |