> ## Documentation Index > Fetch the complete documentation index at: https://milford.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Run a flow > Runs the flow and returns its trace. The response is `200` even when a node failed, so check `ok`. Send `Accept: text/event-stream` to receive events while the run progresses. The event names are `node:start`, `node:done`, `node:error`, `node:skipped` and `provider:call`, and the last event is `result` with the same body as the JSON response. If the server is busy, the stream ends with a `result` event that carries an `error` instead of an HTTP `503`. Closing the connection cancels the run. Send an `Idempotency-Key` to make retries safe. A retry with the same key and input returns the first successful result with the header `Idempotent-Replayed: true` instead of running the flow again. The header is ignored for event streams. ## OpenAPI ````yaml /openapi.yaml post /v1/flows/{id}/run openapi: 3.1.0 info: title: Milford HTTP API version: 0.0.1 description: > Run flows, list them, and receive signed webhooks. The server is stateless and has no database. Generate a client for your language from this file with any OpenAPI generator. servers: - url: http://localhost:8080 security: - bearer: [] paths: /v1/flows/{id}/run: post: summary: Run a flow description: > Runs the flow and returns its trace. The response is `200` even when a node failed, so check `ok`. Send `Accept: text/event-stream` to receive events while the run progresses. The event names are `node:start`, `node:done`, `node:error`, `node:skipped` and `provider:call`, and the last event is `result` with the same body as the JSON response. If the server is busy, the stream ends with a `result` event that carries an `error` instead of an HTTP `503`. Closing the connection cancels the run. Send an `Idempotency-Key` to make retries safe. A retry with the same key and input returns the first successful result with the header `Idempotent-Replayed: true` instead of running the flow again. The header is ignored for event streams. operationId: runFlow parameters: - name: id in: path required: true description: Flow id. schema: type: string - name: Idempotency-Key in: header required: false description: > Any string that is unique per logical request, for example an MQ message id. Results are kept for `server.idempotencyTtlMs` (default 10 minutes), per server instance, and are lost on restart. Failed runs are not kept, so a retry after a failure runs again. schema: type: string requestBody: required: false content: application/json: schema: type: object properties: input: type: object description: Run input. Templates read it as `{{input.field}}`. additionalProperties: true example: input: service: payments message: 'Connection refused: db-primary:5432' responses: '200': description: The run finished. Check `ok` for node failures. headers: Idempotent-Replayed: description: >- Present with the value `true` when the result is a replay of an earlier request with the same key. schema: type: string const: 'true' content: application/json: schema: $ref: '#/components/schemas/RunResult' text/event-stream: schema: type: string description: Server-sent events. See the operation description. '400': description: The body is not JSON, or `input` is not an object. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '404': description: Unknown flow id. content: application/json: schema: $ref: '#/components/schemas/Error' '413': $ref: '#/components/responses/TooLarge' '422': description: The `Idempotency-Key` was already used with a different input. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: The engine could not run the flow. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Too many runs are active. Retry after the delay in `Retry-After`. headers: Retry-After: schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RunResult: type: object required: - ok - runId - nodes properties: ok: type: boolean description: False when any node failed. runId: type: string nodes: type: object description: The trace, keyed by node id. additionalProperties: $ref: '#/components/schemas/NodeState' output: $ref: '#/components/schemas/NodeResult' description: Result of the flow's `output` node, when one ran. Error: type: object required: - error properties: error: type: string NodeState: type: object required: - status properties: status: type: string enum: - done - error - skipped result: $ref: '#/components/schemas/NodeResult' ms: type: number description: Node duration in milliseconds. NodeResult: type: object required: - success properties: success: type: boolean output: type: string description: Text that downstream templates can use. data: description: >- Structured value. For a `decision` node it holds `choice`, `confidence`, `probabilities` and more. error: type: string responses: Unauthorized: description: The bearer token is missing or wrong. content: application/json: schema: $ref: '#/components/schemas/Error' TooLarge: description: The body is larger than `server.maxBodyBytes`. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearer: type: http scheme: bearer description: One of `server.auth.tokens`. With no tokens configured the API is open. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.