---
title: "Create Template Run"
method: POST
path: "/v1/flows/templates/{template_id}/runs"
tags: ["Flows", "Templates"]
---

# Create Template Run

`POST /v1/flows/templates/{template_id}/runs`

Start a run of a flows template. Pass `version_id` to pin a snapshot, or omit it / pass `latest` to run the latest published version. Set input values under `inputs`, keyed by input port id. The response is the run in its initial state, with every output already listed under its port id in `outputs`. Include `webhook` to receive a `flows_template_run` event carrying the finished run once its `status` is `completed` or `failed`; this is the recommended way to wait. Without one, fetch `GET /v1/flows/templates/{template_id}/runs/{run_id}` at a modest interval until the `status` is terminal.

## Path parameters

- `template_id` string, required — The ID of the template, as shown in the ElevenLabs app or by `GET /v1/flows/templates`.

## Headers

- `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

## Request body

- TemplateRunCreateRequest — Request body of ``POST /v1/flows/templates/{template_id}/runs``.
  - `inputs` object, required — Input values keyed by input port id. Every input port of the version being run must be given; a missing or unknown id is rejected. Pass `{}` for a template with no inputs.
  - `version_id` string, nullable — The template snapshot to run. Pass a specific version id to pin that snapshot, or `latest` (the default when omitted) to run the template's most recently published version. Only published versions can be pinned, except by the template's owner, who may also pin an unpublished saved snapshot to try it out before publishing. The live draft is never run through this API.
  - `webhook` union
    - WebhookTargetAll — Deliver the result to all of the workspace's configured flows webhooks.
      - `type` 'all', required — Send the result to all of the workspace's configured flows webhooks.
    - WebhookTargetIds — Deliver the result to specific configured flows webhooks.
      - `type` 'ids', required — Send the result to the listed flows webhooks.
      - `ids` string[], required — The IDs of the workspace flows webhooks to deliver the result to. Each must be one of the workspace's configured flows webhooks.

## Response `200`

Successful Response

- TemplateRunResponse — A template run and its outputs. Every output exists from the moment the run is created and reports its own `status`; the run's `status` rolls them up, and the run is finished once it is `completed` or `failed`.
  - `id` string, required — The unique identifier of the run.
  - `template_id` string, required — The template this run executed, so a webhook consumer running several templates can tell their runs apart without keeping a run-to-template map.
  - `version_id` string, required — The template version this run executed. Resolved when the run is created, so a run started with `latest` records the concrete version it ran.
  - `status` 'pending' | 'generating' | 'completed' | 'failed', required — Where a run, or one of its outputs, is in its lifecycle. The run's is rolled up from its outputs' (``aggregate_output_statuses``). A class rather than a ``Literal`` so it publishes as one named enum instead of being inlined into every kind.
  - `outputs` object, required — The run's outputs, keyed by output port id. Each is a `TemplateOutput` discriminated on `type`, the `type` of its port's `content_schema`.

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-22** `6fb9be1a19f5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/changes/v1/flows/templates/:template_id/runs/post.md)

---

[API](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/elevenlabs/apis/elevenlabs-api-documentation/revisions/48a38e3b0dbd?raw)