---
title: "Run a workflow"
method: POST
path: "/api/v1/workflows/{id}/run"
tags: ["workflows"]
---

# Run a workflow

`POST /api/v1/workflows/{id}/run`

## Request

- Base URL: `https://toolforte.com`
- URL: `https://toolforte.com/api/v1/workflows/{id}/run`
- Auth: HTTP bearer

Run a saved workflow: an ordered chain of tool calls where each step can read an earlier step's output. The id is the workflow id from /workflows. Every step that runs costs its own tool's credits, charged before it runs, so a chain that stops halfway is billed for the steps that happened and no more. Workflows belong to an account, so the key must be one created while signed in.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `inputs` object: Values for the workflow's declared inputs, keyed by input key.

## Response `200`

The run finished, successfully or with a failed step. `stopReason` says which, `steps` holds every step that ran, and `creditsCharged` is what it actually cost.

- object
  - `ok` boolean
  - `data` object
    - `ok` boolean
    - `runId` string
    - `output` object
      - `words` integer
      - `characters` integer
    - `steps` object[]
      - `stepId` string
      - `capabilityId` string
      - `ok` boolean
      - `output` object
        - `valid` boolean
        - `country` string
      - `durationMs` integer
    - `creditsCharged` integer
    - `durationMs` integer
    - `stopReason` string

## Other responses

- `400`: The stored definition can no longer run, for example because a tool it uses was withdrawn. Nothing ran and nothing was charged; `issues` names each problem.
- `401`: Missing, invalid, or revoked API key
- `402`: The balance ran out partway through. The steps that did run are in the body and were charged; the rest were not.
- `403`: This key is not linked to an account, and workflows belong to an account.
- `404`: No workflow with this id belongs to the key's account
- `409`: The workflow is turned off
- `503`: Usage metering was unavailable, so the run stopped rather than run unmetered.
- `504`: The run passed the time limit for a whole workflow and was stopped.

---

[API](https://skmtc.dev/toolforte/apis/toolforte-api.md) · [All operations](https://skmtc.dev/toolforte/apis/toolforte-api/llms.txt) · [OpenAPI document](https://skmtc.dev/toolforte/apis/toolforte-api/revisions/4d814d484dfc?raw)