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.

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" } }'

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 or comparable-deals 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.

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.

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

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

​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

Track a run to completion

Run a workflow from MCP

Manage runs

Trigger from external events

Next steps