> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Automate multi-step research and work product with Metal AI workflows.

Workflows are Metal's automation engine. A workflow chains together steps such as data lookups, AI reasoning, and 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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
graph LR
  Workflow -->|create run| Run
  Run -->|produces| Output
```

## Running a workflow

<Steps>
  <Step title="Find the workflow">
    List your workflows to get the `id` of the one you want to run.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl https://api.metal.ai/v1/workflows \
      -H "x-metal-client-id: $METAL_CLIENT_ID" \
      -H "x-metal-api-key: $METAL_API_KEY"
    ```
  </Step>

  <Step title="Create a run">
    Trigger a run with the inputs the workflow expects.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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" } }'
    ```
  </Step>

  <Step title="Check run status">
    Poll the run to follow its progress and read its output when it completes.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    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"
    ```
  </Step>
</Steps>

<Info>
  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.
</Info>

## 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](/guides/webhooks) for how to configure and call a workflow's webhook trigger.

<Tip>
  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.
</Tip>