Sign in
Flows
Templates

Create Template Run

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.

post/v1/flows/templates/{template_id}/runs

Path parameters

template_idstring required

The ID of the template, as shown in the ElevenLabs app or by GET /v1/flows/templates.

The ID of the template, as shown in the ElevenLabs app or by GET /v1/flows/templates.

Headers

xi-api-keystring 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.

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

inputsobject 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_idstring 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.

Example request

{
  "inputs": {
    "prompt": "a corgi on a surfboard",
    "reference": {
      "asset_id": "5xM2KqOnZyce22SPZ9d4",
      "type": "asset"
    }
  },
  "version_id": "latest",
  "webhook": {
    "type": "all"
  }
}

Response

Successful Response

idstring required

The unique identifier of the run.

template_idstring 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_idstring 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.

outputsobject 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.

Example response

{
  "id": "sess_JWr5N6X9ZTqf8jD2LmQb",
  "outputs": {
    "marketing_title": {
      "content": "Ride the wave.",
      "id": "Kx2mP7Y4WVrg9kE3NnRc",
      "status": "completed",
      "type": "string"
    },
    "product_demo": {
      "id": "QWr5N6X9ZTqf8jD2La3B",
      "status": "generating",
      "type": "video"
    },
    "product_still": {
      "content_mime_type": "image/png",
      "content_url": "https://storage.googleapis.com/generations/JWr5N6X9ZTqf8jD2LmQb",
      "id": "JWr5N6X9ZTqf8jD2LmQb",
      "status": "completed",
      "type": "image"
    }
  },
  "status": "generating",
  "template_id": "tmpl_abc123",
  "version_id": "ver_01hxyz"
}

Changes

Changed in 1 of the 49 revisions of this API.1