---
name: layer-run-workflows
description: Discover and run Layer Blueprint workflows — saved, node-based asset pipelines a studio has already built — and read back their outputs. Use when a repeatable multi-step pipeline should run rather than a single generation, when asked to run a named workflow, or when a live-service content pipeline needs to be driven from code.
---

# Run a Layer Blueprint workflow

A Blueprint workflow is a saved node graph: several generations, transforms, and conditionals
wired together and published in a workspace. Running one is a single call, and it is the right
tool whenever a pipeline already exists — you do not have to reassemble it from individual
generations.

## 1. Find the workflow and its inputs

```bash
curl -H "Authorization: Bearer $LAYER_TOKEN" \
  "https://api.app.layer.ai/api/v2/workspaces/$WORKSPACE_ID/workflows?search=icon"
```

Each entry carries `workflow_id`, `name`, `description`, `modality`, and its declared `inputs`.
Every input has a `name` (the key you send), a `type` (`string`, `number`, `boolean`, `file`,
`prompt`, …), a `value_schema`, whether it is `required`, and a `default`. Read these rather than
guessing: a workflow's inputs are defined by whoever built it.

## 2. Estimate

```json
POST /v2/workspaces/{workspace_id}/workflows/{workflow_id}/estimate
{ "inputs": { "subject": "frost golem", "variations": 4 } }
```

Returns `estimated_price_creative_units`, `output_counts` (how many assets of each kind the run
will produce), and `has_sufficient_creative_units`. Check that last field first — it is free to
ask, and there is no sandbox to try it in.

## 3. Execute

```json
POST /v2/workspaces/{workspace_id}/workflows/{workflow_id}/runs
{ "inputs": { "subject": "frost golem", "variations": 4 }, "session_name": "Frost golem pass" }
```

Returns `run_id` and `poll_interval_seconds`. `session_id` is optional — pass one to keep the run
inside an existing session, or `session_name` to have a new one named.

## 4. Poll

`GET /v2/workspaces/{workspace_id}/workflows/{workflow_id}/runs/{run_id}` on the interval it
returns. The response carries an overall `status`, plus `steps[]` — each with its own `name`,
`status` (`pending`, `running`, `success`, `failure`, `cancelled`), and `error`. When a run
fails, the failing step names what went wrong; report that rather than the top-level status
alone. On success, `outputs` carries the assets and `actual_price_creative_units` the real cost.

## Over MCP

`list_workflows`, `estimate_workflow_price`, `execute_workflow`, `get_workflow_run`, and
`cancel_workflow_run` on `https://mcp.app.layer.ai/mcp`. Call `get_workflow_instructions` before
the first run. `execute_workflow` carries an MCP Apps `ui://` view, so a host that negotiates the
`io.modelcontextprotocol/ui` extension renders the run inline instead of returning a run id.

Workflow runs are not currently subject to the per-user generation rate limits.

## Reference

- REST reference: <https://layer.ai/docs/v2/rest-api>
- Async jobs and polling: <https://layer.ai/docs/async-jobs>