Automate research with workflows

Workflows are Metal’s automation engine: they chain data lookups, AI reasoning, and document generation into repeatable research. You author workflows visually in the Metal app, then use the API to run and monitor them. Each execution is a run. For the underlying model, see the workflows concept. To add a reusable assessment before running your workflow, see Add scoring to a workflow. It covers rubric instructions, evidence, structured outputs, and publication mappings.

Find the workflow to run

List your workflows to get the id of the one you want to execute.

curl https://api.metal.ai/v1/workflows \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"

Create a run

Trigger a run with the inputs the workflow expects. Runs are asynchronous: this returns immediately with a run record.

curl -X POST https://api.metal.ai/v1/workflows/665f1c2a9b1e4a0012a3b4c5/runs \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "companyId": "665f1c2a9b1e4a0012a3b4c6" } }'

Dry-run a workflow

Pass dryRun: true in the create-run body to validate the workflow without executing side-effects. Read-only tools still run so the agent can gather context; write and destructive tools have their arguments validated against the tool schema instead of executing. Permission prompts are skipped.

curl -X POST https://api.metal.ai/v1/workflows/665f1c2a9b1e4a0012a3b4c5/runs \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "companyId": "665f1c2a9b1e4a0012a3b4c6" }, "dryRun": true }'

A dry run stays a dry run: POST /v1/workflow-runs/{id}/retry inherits the dryRun flag from the source run, so the retry also validates instead of executing. To execute for real, create a new run without dryRun.

Track a run to completion

Poll the run until it finishes, then read its output.

import os
import time
import requests

BASE = "https://api.metal.ai/v1"
headers = {
    "x-metal-client-id": os.environ["METAL_CLIENT_ID"],
    "x-metal-api-key": os.environ["METAL_API_KEY"],
    "Content-Type": "application/json",
}

def run_workflow(workflow_id, input_payload, interval=10, timeout=600):
    run = requests.post(
        f"{BASE}/workflows/{workflow_id}/runs",
        headers=headers,
        json={"input": input_payload},
    ).json()["data"]

    terminal = {"completed", "failed", "cancelled"}
    deadline = time.time() + timeout
    while time.time() < deadline:
        run = requests.get(f"{BASE}/workflow-runs/{run['id']}", headers=headers).json()["data"]
        if run["status"].lower() in terminal:
            return run
        time.sleep(interval)
    raise TimeoutError(f"Run {run['id']} did not finish in {timeout}s")

Prefer events over polling for long-running workflows. A webhook trigger lets an external system both start a run and be notified when it finishes.

Run a workflow from MCP

The Metal MCP server exposes the same workflow run path to MCP-compatible assistants such as Cursor, Claude, and ChatGPT. Use it when you want an assistant to discover the workflow, inspect required inputs, launch a run, and read the output without writing API code. The usual MCP sequence is:

list_workflows — find the workflow ID. For example, search for a comparable-company, comparable-deals, or conference-prep workflow by name or description.
get_workflow — inspect inputSchema and inputUiSchema so you know which company, deal, document, folder, or other inputs the workflow expects.
run_workflow — start the run with an input object that matches the schema.
get_workflow_run — poll until the run reaches a terminal status, then read outputs, artifacts, citations, or failures.

{
  "name": "run_workflow",
  "arguments": {
    "workflowId": "665f1c2a9b1e4a0012a3b4c5",
    "input": {
      "companyId": "665f1c2a9b1e4a0012a3b4c6"
    }
  }
}

If the run enters a human review state, inspect the pending step with get_workflow_run_step and complete the review with review_workflow_hitl_step when appropriate. To stop a run that is still in progress, the assistant can call cancel_workflow_run. Cancelling does not undo actions the run has already taken.

MCP access uses the signed-in Metal user’s permissions. If list_workflows does not return the workflow, confirm that the user can see and run it in the Metal app. Built-in productized workflows such as DDQ Solver have no workflow-API or MCP run path. See Run a workflow for how MCP list_workflows relates to GET /v1/workflows.

Manage runs

Action	Endpoint
List runs for a workflow	`GET /v1/workflows/{id}/runs`
Get a run	`GET /v1/workflow-runs/{id}`
Retry a failed run	`POST /v1/workflow-runs/{id}/retry`
Re-run with the same inputs	`POST /v1/workflow-runs/{id}/rerun`
Cancel an in-progress run	`POST /v1/workflow-runs/{id}/cancel`

Trigger from external events

Instead of calling the API yourself, you can expose a webhook trigger on a workflow so an external system starts a run when something happens on its side — a new deal in your CRM, a file landing in storage, or a form submission.

curl -X POST https://api.metal.ai/webhooks/workflows/your-workflow-slug \
  -H "Content-Type: application/json" \
  -d '{ "companyId": "665f1c2a9b1e4a0012a3b4c6" }'

See webhooks for configuring the trigger and securing its secret.

Next steps

Run over a list

Screen an entire set of targets in one pass.

Trigger from events

Start runs from your own systems without managing API keys.

Core tasks

API essentials

Automate research with workflows

Find the workflow to run

Create a run

Dry-run a workflow

Track a run to completion

Run a workflow from MCP

Manage runs

Trigger from external events

Next steps

Run over a list

Trigger from events

​Find the workflow to run

​Create a run

​Dry-run a workflow

​Track a run to completion

​Run a workflow from MCP

​Manage runs

​Trigger from external events

​Next steps

Run over a list

Trigger from events

Find the workflow to run

Create a run

Dry-run a workflow

Track a run to completion

Run a workflow from MCP

Manage runs

Trigger from external events

Next steps