Skip to main content
GET
/
traces
/
session
/
{sessionId}
/
{traceId}
Get Trace Details
curl --request GET \
  --url https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId} \
  --header 'x-api-key: <api-key>'
import requests

url = "https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}")
  .header("x-api-key", "<api-key>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://voice-livekit.studio.lyzr.ai/v1/traces/session/{sessionId}/{traceId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
{
  "trace": {
    "traceId": "<string>",
    "name": "<string>",
    "sessionId": "<string>",
    "timestamp": "2023-11-07T05:31:56Z",
    "latencySeconds": 123,
    "totalCostUsd": 123,
    "htmlPath": "<string>",
    "observations": [
      {
        "id": "<string>",
        "traceId": "<string>",
        "parentObservationId": "<string>",
        "type": "<string>",
        "name": "<string>",
        "level": "<string>",
        "startTime": "2023-11-07T05:31:56Z",
        "endTime": "2023-11-07T05:31:56Z",
        "completionStartTime": "2023-11-07T05:31:56Z",
        "statusMessage": "<string>",
        "model": "<string>",
        "modelParameters": {},
        "input": "<string>",
        "output": "<string>",
        "metadata": {},
        "usageDetails": {},
        "costDetails": {},
        "environment": "<string>"
      }
    ]
  }
}
{
  "error": "Trace not found.",
  "details": "<string>"
}
Dive deep into the exact execution steps of a single Voice Agent action. While the List Session Traces endpoint gives you a high-level overview of a call’s latency and cost, this endpoint exposes the raw, underlying data. It acts as an X-ray for your agent, revealing the exact prompts sent to the LLM, the model parameters used, and the precise token breakdown.
Authentication Required: You must include your API key in the x-api-key header to authenticate this request.

​
Required Parameters

You need two identifiers to retrieve a specific trace:
  1. sessionId (Path): The UUID of the LiveKit session where the action occurred.
  2. traceId (Path): The ID of the specific trace you want to inspect.

​
Demystifying the observations Array

The core value of this endpoint lies in the observations array. An observation represents a single unit of work (like an LLM generation, a tool call, or a database retrieval). When debugging agent behavior, look closely at these fields within each observation:
  • input & output: The exact string or JSON payload sent to the model, and the exact string returned. This is critical for debugging why an agent said something unexpected.
  • model & modelParameters: Confirms which model (e.g., gpt-4o) handled the request and the temperature/top_p settings applied at that exact moment.
  • usageDetails & costDetails: A granular breakdown of prompt tokens vs. completion tokens, and the exact fractional USD cost associated with this single step.
  • latency & Timing: Compare startTime, completionStartTime (time to first token), and endTime to pinpoint exactly where delays are happening in your pipeline.

​
Troubleshooting Errors

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
sessionId
string<uuid>
required

The unique UUID of the LiveKit session.

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

​
traceId
string
required

The specific identifier of the trace to retrieve.

Example:

"trace-abc-123"

Response

Trace details retrieved successfully.

​
trace
object