Query run logs

curl --request POST \
  --url https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "kinds": [
    "user"
  ],
  "levels": [
    "fatal"
  ],
  "debugKinds": [
    "llm"
  ],
  "turns": [
    0
  ],
  "search": "<string>",
  "detail": "summary",
  "limit": 50,
  "offset": 0,
  "order": "asc"
}'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kinds": [
      "user"
    ],
    "levels": [
      "fatal"
    ],
    "debugKinds": [
      "llm"
    ],
    "turns": [
      0
    ],
    "search": "<string>",
    "detail": "summary",
    "limit": 50,
    "offset": 0,
    "order": "asc"
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "kinds": [
        "user"
      ],
      "levels": [
        "fatal"
      ],
      "debugKinds": [
        "llm"
      ],
      "turns": [
        0
      ],
      "search": "<string>",
      "detail": "summary",
      "limit": 50,
      "offset": 0,
      "order": "asc"
    },
)
data = response.json()

{
  "total": 0,
  "turnCount": 0,
  "counts": {
    "byKind": {
      "user": 0,
      "agent": 0,
      "debug": 0,
      "check": 0,
      "system": 0
    },
    "byLevel": {
      "fatal": 0,
      "error": 0,
      "warn": 0,
      "info": 0,
      "debug": 0
    },
    "byDebugKind": {
      "llm": 0,
      "tokens": 0,
      "tool": 0,
      "agent": 0,
      "kb": 0,
      "variables": 0,
      "node": 0,
      "other": 0
    }
  },
  "tokens": [
    {
      "model": "<string>",
      "calls": 0,
      "inputTokens": 0,
      "outputTokens": 0,
      "totalTokens": 0,
      "credits": 0
    }
  ],
  "matches": 0,
  "entries": [
    {
      "index": 0,
      "turn": 0,
      "time": "<string>",
      "kind": "user",
      "type": "<string>",
      "level": "fatal",
      "debugKinds": [
        "<StableLogDebugKind>"
      ],
      "source": "<string>",
      "ref": "<StableLogEntryRef>",
      "message": "<string>",
      "fields": {},
      "raw": {}
    }
  ],
  "hasMore": true,
  "nextOffset": 0,
  "truncated": true
}

Query run logs

Searches the log of one test run, filtering entries by kind, level, debug kind, turn or text, a page at a time. Each page also reports the log’s total entry count and token use per model; send `nextOffset` back for the next page.

POST

/v1/stable/test-run/{runID}/logs

Query run logs

curl --request POST \
  --url https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs \
  --header 'Authorization: Bearer <token>'
  --header 'Content-Type: application/json' \
  --data '{
  "kinds": [
    "user"
  ],
  "levels": [
    "fatal"
  ],
  "debugKinds": [
    "llm"
  ],
  "turns": [
    0
  ],
  "search": "<string>",
  "detail": "summary",
  "limit": 50,
  "offset": 0,
  "order": "asc"
}'

const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "kinds": [
      "user"
    ],
    "levels": [
      "fatal"
    ],
    "debugKinds": [
      "llm"
    ],
    "turns": [
      0
    ],
    "search": "<string>",
    "detail": "summary",
    "limit": 50,
    "offset": 0,
    "order": "asc"
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/test-run/<runID>/logs?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "kinds": [
        "user"
      ],
      "levels": [
        "fatal"
      ],
      "debugKinds": [
        "llm"
      ],
      "turns": [
        0
      ],
      "search": "<string>",
      "detail": "summary",
      "limit": 50,
      "offset": 0,
      "order": "asc"
    },
)
data = response.json()

{
  "total": 0,
  "turnCount": 0,
  "counts": {
    "byKind": {
      "user": 0,
      "agent": 0,
      "debug": 0,
      "check": 0,
      "system": 0
    },
    "byLevel": {
      "fatal": 0,
      "error": 0,
      "warn": 0,
      "info": 0,
      "debug": 0
    },
    "byDebugKind": {
      "llm": 0,
      "tokens": 0,
      "tool": 0,
      "agent": 0,
      "kb": 0,
      "variables": 0,
      "node": 0,
      "other": 0
    }
  },
  "tokens": [
    {
      "model": "<string>",
      "calls": 0,
      "inputTokens": 0,
      "outputTokens": 0,
      "totalTokens": 0,
      "credits": 0
    }
  ],
  "matches": 0,
  "entries": [
    {
      "index": 0,
      "turn": 0,
      "time": "<string>",
      "kind": "user",
      "type": "<string>",
      "level": "fatal",
      "debugKinds": [
        "<StableLogDebugKind>"
      ],
      "source": "<string>",
      "ref": "<StableLogEntryRef>",
      "message": "<string>",
      "fields": {},
      "raw": {}
    }
  ],
  "hasMore": true,
  "nextOffset": 0,
  "truncated": true
}

Authorizations

Authorization

string

header

required

Voiceflow bearer token

Path Parameters

runID

string

required

Query Parameters

projectID

string

required

The ID of the project to operate on.

environmentAlias

string

required

The alias of the environment to operate on (e.g. main).

Body

kinds

object[]

Keep only entries of these kinds. Omit to keep every kind.

levels

object[]

Keep only entries at these levels, for example ["fatal", "error", "warn"] for what went wrong.

debugKinds

object[]

Keep only debug entries of these kinds. Setting it leaves out every entry that is not a debug log.

turns

integer[]

Keep only entries of these turns. Turn 0 holds anything logged before the first input.

string

Keep only entries whose message or recorded data contains this text, ignoring case. It is plain text, not a regular expression. Separate alternatives with |, as in "timeout|denied", to keep entries that contain any of them.

detail

object

default:"summary"

Show child attributes

limit

integer

default:50

The most entries to return in one page.

offset

integer

default:0

How many matching entries to skip, for paging.

order

object

default:"asc"

Show child attributes

Response

200 - application/json

Returns one page of the log entries that match the filters, with the counts for the whole log, the token use per model, and nextOffset for the next page (null on the last page).

total

integer

required

Entries in the whole log.

turnCount

integer

required

The last turn the log reaches.

counts

object

required

How many entries of each kind, level and debug kind the whole log holds, before any filter.

Show child attributes

byKind

object

required

Show child attributes

user

integer

required

agent

integer

required

debug

integer

required

check

integer

required

system

integer

required

byLevel

object

required

Show child attributes

fatal

integer

required

error

integer

required

warn

integer

required

info

integer

required

debug

integer

required

byDebugKind

object

required

Show child attributes

llm

integer

required

tokens

integer

required

tool

integer

required

agent

integer

required

integer

required

variables

integer

required

node

integer

required

other

integer

required

tokens

object[]

required

Token use per model over the whole log, largest first.

Show child attributes

model

string

required

calls

integer

required

Model calls that logged their token use.

inputTokens

number

required

outputTokens

number

required

totalTokens

number

required

credits

number

required

Voiceflow credits the calls used, 0 when the log does not record them.

matches

integer

required

Entries that pass every filter.

entries

object[]

required

This page of the matching entries.

Show child attributes

index

integer

required

Where the entry sits in the whole log, oldest first, from 0.

turn

integer

required

The turn of the entry. Each user input, a launch included, starts the next turn. Anything logged before the first input, such as a test run's greeting, is turn 0.

time

string

required

When the entry was logged, as an ISO 8601 timestamp.

kind

object

required

user: what the user sent. agent: what the agent said or showed. debug: a runtime debug log. check: a test check result, test runs only. system: any other event, such as a block, a workflow or the end.

Available options: user, agent, debug, check, system

StableLogEntryKind — see its attributes above

type

string

required

The trace or request type as recorded, such as text, debug, launch or end.

level

object

required

A debug log carries its own level. A failed check is error. Every other entry is info.

Available options: fatal, error, warn, info, debug

StableLogLevel — see its attributes above

debugKinds

object[]

Debug entries only. An entry can be of several kinds.

StableLogDebugKind — see its attributes above

source

string

Debug entries only: the part of the runtime that logged it, such as Agent.

ref

object

Show child attributes

type

string

required

What the entry is about: agent, function, api-tool, integration-tool, prompt or node.

string

The ID of that agent, tool, prompt or workflow step.

name

string

Its name; for a workflow step, the name of its workflow.

message

string

required

What happened, in one line of at most 500 characters.

fields

object

Up to 24 small values recorded with the entry, such as model, tokens, latency, status or a variable before and after. Nested keys are joined with dots, and strings are cut at 200 characters.

raw

object

With detail full only: the entry as recorded, with strings cut at 4,000 characters and lists at 50 items.

hasMore

boolean

required

nextOffset

integer

required

The offset of the next page, or null when this page reaches the last match.

truncated

boolean

required

True when the page stopped before limit to stay under about 30,000 tokens. Continue from nextOffset.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Query run logs

Authorizations

Path Parameters

Query Parameters

Body

Response

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks