Runs

Allows you to start a new run, i.e. resolve templates and send the fully formatted prompt to an LLM of your choice.

• Select the active template set version based on version and environment as described in Flows

• Take the prompt entrypoint and start recursively replacing tokens given in parameters. Parameters always precede descending into a template of the same name

• Send the prompt to the LLM chosen as default for the selected entrypoint in the respective version, unless overrideModel is specified. The model must be one of Models

• Waits until the request is finished and returns both the formatted request and the LLM response, along with some metadata

POST/api/v1/flows/{flowId}/runs

Path parameters

flowId*string

Body

application/jsontext/jsonapplication/*+json

parametersnullable object

environmentnullable string

overrideModelnullable string

tagsnullable array of string

entrypointnullable string

versionnullable string

Response

200

OK

Body

text/plainapplication/jsontext/json

creditsUsedinteger (int64)

millisecondsinteger (int32)

idnullable string

timestampstring (date-time)

flowIdnullable string

tenantIdnullable string

userIdnullable string

flowRequestobject

requestsnullable array of object

responsesnullable array of object

creditsLeftnullable integer (int64)

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/api/v1/flows/{flowId}/runs', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "parameters": {},
      "tags": [
        null
      ]
    }),
});
const data = await response.json();

Response

200

{
  "creditsUsed": 1,
  "milliseconds": 1,
  "id": "text",
  "timestamp": "2025-02-05T10:43:56.661Z",
  "flowId": "text",
  "tenantId": "text",
  "userId": "text",
  "flowRequest": {
    "parameters": {},
    "environment": "text",
    "overrideModel": "text",
    "tags": [
      "text"
    ],
    "entrypoint": "text",
    "version": "text"
  },
  "requests": [
    {
      "id": "text",
      "idCreated": "2025-02-05T10:43:56.661Z",
      "shuttleRequestId": "text",
      "messages": [
        {
          "role": "client",
          "text": "text"
        }
      ],
      "model": "text",
      "maxTokens": 1,
      "seed": 1,
      "temperature": 1,
      "topP": 1,
      "topK": 1
    }
  ],
  "responses": [
    {
      "model": "text",
      "provider": "text",
      "usage": {
        "tokensIn": 1,
        "tokensOut": 1,
        "tokensTotal": 1,
        "costUsd": 1,
        "costCredits": 1
      },
      "textResponse": "text",
      "verbatimResponse": "text"
    }
  ],
  "creditsLeft": 1
}