Skip to main content
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.

​
Manage runs

ActionEndpoint
List runs for a workflowGET /v1/workflows/{id}/runs
Get a runGET /v1/workflow-runs/{id}
Retry a failed runPOST /v1/workflow-runs/{id}/retry
Re-run with the same inputsPOST /v1/workflow-runs/{id}/rerun
Cancel an in-progress runPOST /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.