Skip to main content
Workflows are Metal’s automation engine. A workflow chains together steps — data lookups, AI reasoning, document generation — to automate research that would otherwise be manual. Each execution of a workflow is a run.

​
Workflows and runs

  • A workflow is the definition: the steps, inputs, and configuration.
  • A run is a single execution of a workflow against specific inputs.
You manage definitions with the workflow endpoints and execute them by creating runs.

​
Running a workflow

1

Find the workflow

List your workflows to get the id of the one you want to run.
curl https://api.metal.ai/v1/workflows \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
2

Create a run

Trigger a run with the inputs the workflow expects.
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": "665f1c2a9b1e4a0012a3b4c5" } }'
3

Check run status

Poll the run to follow its progress and read its output when it completes.
curl https://api.metal.ai/v1/workflow-runs/665f1c2a9b1e4a0012a3b4c6 \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
Runs are asynchronous. Creating a run returns immediately with a run record; poll GET /v1/workflow-runs/{id} (or use a webhook trigger) to track completion.

​
Managing runs

Beyond creating and reading runs, you can:
  • 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
  • List runs for a workflow: GET /v1/workflows/{id}/runs

​
Versioning

Workflow definitions are versioned. You can list versions (GET /v1/workflows/{id}/versions) and restore a previous version (POST /v1/workflows/{id}/versions/restore) if a change needs to be rolled back.

​
Triggering from external systems

Workflows can be triggered by inbound webhooks in addition to API calls. This lets an external system kick off research when an event happens on its side. See Webhooks for how to configure and call a workflow’s webhook trigger.
Build and edit workflow definitions in the Metal app, then use the API to trigger and monitor runs programmatically. This keeps complex authoring visual while automation stays in code.