Session observability

Overview

The session observability endpoints return the details of a single session, including its transcript, agent logs, trace spans, and metrics, and a download URL for the recording. Use them to debug a deployed agent. To find a session, see Sessions.

Every endpoint here needs the Admin role on the project.

Session data contains personal information

Transcripts, recordings, and logs can contain personal information about the people who talk to your agent. Use this data only for the task at hand. Don't copy it into other tools or share it.

Observability data exists only for sessions that run while user data recording is on. Projects created in the dashboard have it on by default. Projects that you create with the API have it off unless you set enableUserDataRecording to true. To turn it on for an existing project, update the project.

When recording is off and no data exists, a request returns 400 with an ObservabilityDisabled detail that links to the project setting. Turning recording off doesn't delete data that's already recorded.

Agents export session data during the session and for a short time after it ends. A read returns the data that exists when it runs, and dataStatus.state tells you if more data can still arrive:

DATA_STATE_SESSION_ACTIVE: the session is active, and its agents can export more data.
DATA_STATE_SETTLING: the session ended less than 2 minutes ago, and an agent joined it. More data can still arrive. Read again after dataStatus.retryAfterSeconds.
DATA_STATE_SETTLED: the session ended 2 minutes ago or more, or no agent joined it. LiveKit expects no more data. The data can still be incomplete, for example when an agent didn't export all of it.

While the session is active or settling, a recording URL request for a recording that doesn't exist yet returns an empty url. After that, it returns 404.

By default, LiveKit deletes the transcript, logs, traces, metrics, and recording of a session 30 days after the session ends. The session itself stays in the session list after that, without this data. To learn more, see Retention window.

A transcript item is a message, a tool call, a tool result, an agent handoff, or a change to the agent's configuration. Items come in order, with per-turn timing where the agent reported it. The text can differ from what the dashboard shows:

An agent turn can include text-to-speech markup, such as <expr type="expression" label="happy"/>. These endpoints return the markup as text. The dashboard shows each markup tag as a delivery cue instead.
A project with personally identifiable information (PII) redaction publishes the transcript only after it redacts the recording, so the transcript takes longer to appear. A redacted message includes "redacted": true, with each removed value replaced by a <redaction type="..."/> marker.

To call these endpoints from the CLI, use the lk analytics session commands, for example lk analytics session transcript SESSION_ID --user-auth.

Get session transcript

GET

/v0/projects/{projectId}/sessions/{sessionId}/transcript

Returns the conversation of a session as ordered transcript items. The items are messages, tool calls and results, agent handoffs, and agent configuration changes. It is the conversation that the transcript on the dashboard shows.

The agent exports its transcript when the session ends. There is a delay before you can read it, and the length of the delay is not fixed. On a project with PII redaction, you can read it only after LiveKit redacts the session recording. Thus, an ACTIVE session returns the items that exist, usually none, with no error. Read it again after the session ends. An unknown session returns NotFound.

Returns a list of TranscriptItem objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

Other response fields

skippedRecordsinteger

The number of records in this page that the API cannot read as transcript items, and does not return. For example, a record of an item type that the API does not know. Zero when the page is complete.

dataStatusDataStatus

The data status of the session transcript: whether more of it can still arrive.

To learn more, see DataStatus.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/transcript" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "id": "item_f427976e3539",
      "timestamp": "2026-01-15T01:38:58.212Z",
      "message": {
        "role": "ROLE_USER",
        "text": "Hi, I'm checking on order 48213. It still says processing.",
        "interrupted": false,
        "redacted": false,
        "transcriptConfidence": 0.94,
        "startedSpeakingAt": "2026-01-15T01:38:58.212Z",
        "stoppedSpeakingAt": "2026-01-15T01:39:01.405Z",
        "transcriptionDelayMs": 212.4,
        "endOfTurnDelayMs": 528.9,
        "onUserTurnCompletedDelayMs": 3.2
      }
    },
    {
      "id": "item_0cb56594567e",
      "timestamp": "2026-01-15T01:39:02.611Z",
      "message": {
        "role": "ROLE_AGENT",
        "text": "Thanks. Order 48213 shipped this morning and should arrive on Friday.",
        "interrupted": false,
        "redacted": false,
        "startedSpeakingAt": "2026-01-15T01:39:02.611Z",
        "stoppedSpeakingAt": "2026-01-15T01:39:06.807Z",
        "e2eLatencyMs": 1206.3,
        "llmTtftMs": 412.7,
        "ttsTtfbMs": 238.9
      }
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  },
  "skippedRecords": 0,
  "dataStatus": {
    "state": "DATA_STATE_SETTLED",
    "retryAfterSeconds": 0
  }
}

Get session logs

GET

/v0/projects/{projectId}/sessions/{sessionId}/logs

Returns the log records that the agents of a session exported, in time order. These are the records that the logs panel on the dashboard shows. The chat history is not included, because GetSessionTranscript returns it. Evaluation results are included. To get the events of the session, such as participants that join, use AnalyticsService.ListSessionEvents.

An ACTIVE session returns the records that its agents exported up to now. While you page through the records, an agent can export a record with a time that your pages already passed. For example, in oldest-first order, a record with a time earlier than the cursor position. This read does not return that record. A new read returns it. An unknown session returns NotFound. A read filtered by logLevels can return no records because no record has those levels. Thus, only a read with no filter returns the ObservabilityDisabled error.

Returns a list of LogRecord objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

logLevelsArray<LogLevel>

The log levels to return, as the logs filter on the dashboard selects them. For example, only TRACE and FATAL. Returns only the records at these levels. When empty, returns all records, including records with no level, such as a passed evaluation. LOG_LEVEL_UNSPECIFIED returns InvalidArgument.

To learn more, see LogLevel.

sortOrderSortOrder

The sort direction of the timestamps. Defaults to ascending (oldest first).

To learn more, see SortOrder.

Other response fields

dataStatusDataStatus

The data status of the session logs: whether more of them can still arrive.

To learn more, see DataStatus.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/logs" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "id": "f47f38b6-0de6-29a5-9938-4878e4d9b710",
      "timestamp": "2026-01-15T01:39:02.318Z",
      "level": "LOG_LEVEL_INFO",
      "severityText": "INFO",
      "logger": "support-agent",
      "message": "Looked up order 48213",
      "bodyFields": {},
      "attributes": {
        "code.file.path": "/app/src/agent.py",
        "code.function.name": "lookup_order",
        "job_id": "AJ_3kPq8vRtNmXw",
        "room_id": "RM_u52jUOHjoTIF"
      },
      "traceId": "05678c82d9ec6c04939cd5c036a35364",
      "spanId": "0d69aaf02b760616"
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  },
  "dataStatus": {
    "state": "DATA_STATE_SETTLED",
    "retryAfterSeconds": 0
  }
}

Get session traces

GET

/v0/projects/{projectId}/sessions/{sessionId}/traces

Returns the spans that the agents of a session exported, ordered by start time. These are the spans that the trace view on the dashboard shows. Each span names its parent, so you can build the span tree from the pages. The attributes of a span hold the turn and latency fields that the turn view on the dashboard uses, such as lk.generation_id and lk.response.ttft.

An ACTIVE session returns the spans that its agents exported up to now. A span exported after the first page appears only in a new read. The API reads the later pages by offset, so a span exported during your read can move them. Thus, a span can repeat, or a page can skip a span. Remove duplicates by spanId. To get a skipped span, read again from the first page. An unknown session returns NotFound.

Returns a list of Span objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

Other response fields

dataStatusDataStatus

The data status of the session spans: whether more of them can still arrive.

To learn more, see DataStatus.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/traces" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "spanId": "7f2933d4842238f7",
      "traceId": "05678c82d9ec6c04939cd5c036a35364",
      "parentSpanId": "0d69aaf02b760616",
      "name": "start_agent_activity",
      "startTime": "2026-01-15T01:38:54.204Z",
      "endTime": "2026-01-15T01:38:54.604Z",
      "kind": "SPAN_KIND_INTERNAL",
      "status": "SPAN_STATUS_OK",
      "statusMessage": "",
      "attributes": {
        "job_id": "AJ_3kPq8vRtNmXw",
        "lk.agent_label": "support_assistant",
        "lk.agent_name": "support-agent",
        "room_id": "RM_u52jUOHjoTIF"
      },
      "events": [
        {
          "timestamp": "2026-01-15T01:38:54.391Z",
          "name": "agent_state_changed",
          "attributes": {
            "new_state": "listening",
            "old_state": "initializing"
          }
        }
      ]
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  },
  "dataStatus": {
    "state": "DATA_STATE_SETTLED",
    "retryAfterSeconds": 0
  }
}

Get session metrics

GET

/v0/projects/{projectId}/sessions/{sessionId}/metrics

Returns the OpenTelemetry metric points that the agents of a session exported, ordered by time. The points include turn latencies, such as lk.agents.turn.e2e_latency and lk.agents.turn.llm_ttft, token and duration usage, such as lk.agents.usage.llm_input_tokens, and the gen_ai.* histograms. They also include the metrics that the agent's own code recorded.

These are the raw metrics that agents export. They do not exactly match the metrics panel on the dashboard, which calculates its values from the transcript and traces. Only an agent that exports OpenTelemetry metrics to LiveKit Cloud has points. An agent whose code installs its own MeterProvider exports no metrics to LiveKit Cloud, and its sessions return no points.

Some points do not have the labels that their agent exported. LiveKit Cloud groups the series of a session by their attributes only, and gives each group the name of its first point. This has these results. Several metrics can have one name. For example, the input, output, and cached token counts of an LLM all have the name lk.agents.usage.llm_input_tokens. Points of one series with the same time and the same value become one point. When a session has two agents, a point can have the resource attributes of the other agent.

An agent exports its metrics every 30 seconds, and its turn latencies when the session ends. Thus, an ACTIVE session returns the points that its agents exported up to now. An unknown session returns NotFound. A read filtered by names can return no points because no metric has those names. Thus, only a read with no filter returns the ObservabilityDisabled error.

Returns a list of MetricPoint objects, with a pageInfo cursor.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

page.cursorstring

The cursor of the page to return: the nextCursor of the previous page. When empty, the list starts at the first item.

page.pageSizeint32

The maximum number of items to return. When 0, the list uses its default page size.

namesArray<string>

The names of the metrics to return, such as lk.agents.turn.e2e_latency. Returns only the points of these metrics. Each name must match exactly. When empty, returns all metrics. The maximum is 50 names, each 1 to 256 characters.

Other response fields

dataStatusDataStatus

The data status of the session metric points: whether more of them can still arrive.

To learn more, see DataStatus.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/metrics" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "items": [
    {
      "name": "lk.agents.turn.e2e_latency",
      "unit": "s",
      "kind": "METRIC_KIND_HISTOGRAM",
      "startTime": "2026-01-15T01:38:54Z",
      "endTime": "2026-01-15T01:43:12Z",
      "attributes": {
        "job_id": "AJ_3kPq8vRtNmXw",
        "lk.agent_name": "support-agent",
        "room_id": "RM_u52jUOHjoTIF"
      },
      "histogram": {
        "count": "12",
        "sum": 14.73,
        "min": 0.82,
        "max": 1.94,
        "bucketBounds": [
          0.5,
          1,
          1.5,
          2
        ],
        "bucketCounts": [
          "0",
          "3",
          "8",
          "1",
          "0"
        ]
      }
    }
  ],
  "pageInfo": {
    "nextCursor": "",
    "hasMore": false
  },
  "dataStatus": {
    "state": "DATA_STATE_SETTLED",
    "retryAfterSeconds": 0
  }
}

Get session recording URL

GET

/v0/projects/{projectId}/sessions/{sessionId}/recording-url

Returns a short-lived signed URL for a session recording: its audio or its chat history. When the recording doesn't exist and dataStatus.state is DATA_STATE_SESSION_ACTIVE or DATA_STATE_SETTLING, the response has an empty url, because the agent can still upload the recording. In every other state, a session with no recording of that type returns NotFound.

Path parameters

projectId

Required

string

The project ID (p_...).

sessionId

Required

string

The session ID (RM_...).

Query parameters

fileTypeRecordingFileType

The recording to sign a URL for. RECORDING_FILE_TYPE_UNSPECIFIED returns InvalidArgument.

To learn more, see RecordingFileType.

expirySecondsinteger

The time that the URL stays valid, in seconds. Defaults to 900 (15 minutes) when unset or 0. The API clamps a larger value to 900, with no error. expiresAt gives the expiry that the API granted.

Response fields

urlstring

A signed URL that downloads the recording from storage in the data region of the project. The URL needs no credentials and is valid until expiresAt. Audio is Ogg. Chat history is JSON, served with Content-Encoding: gzip. Empty when the recording doesn't exist and dataStatus.state is DATA_STATE_SESSION_ACTIVE or DATA_STATE_SETTLING.

recordingStartedAttimestamp

The time that the recording started, as the agent reported it when it uploaded the recording. Use it to align the audio with the transcript.

expiresAttimestamp

The time that the URL stops working: the time of the request plus the granted expiry, after the 15-minute clamp.

dataStatusDataStatus

The data status of the session recording: whether it can still arrive or change. When url is empty, expiresAt is unset: read again after retryAfterSeconds, or after the session ends.

To learn more, see DataStatus.

Request

curl -X GET "https://beta-api.livekit.cloud/v0/projects/${PROJECT_ID}/sessions/${SESSION_ID}/recording-url" \
  -G \
  --data-urlencode "fileType=RECORDING_FILE_TYPE_AUDIO" \
  -H "Authorization: Bearer $LIVEKIT_SESSION_TOKEN"

Response

{
  "url": "https://example-bucket.s3.us-east-1.amazonaws.com/p_f9779j5lpvh/RM_u52jUOHjoTIF/recording.ogg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20260115%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260115T014500Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=3ebb153fb24e4411400e94a9a92b0ec458c3a8473e51e03cd37d4a34c99dfda6",
  "recordingStartedAt": "2026-01-15T01:38:54.201Z",
  "expiresAt": "2026-01-15T02:00:00Z",
  "dataStatus": {
    "state": "DATA_STATE_SETTLED",
    "retryAfterSeconds": 0
  }
}

Types

Types used by these endpoints.

ConfigUpdate

A change to the agent's instructions or tools during the session.

instructionsstring

The new agent instructions. Empty when the instructions did not change.

toolsAddedArray<string>

The tools the agent gained.

toolsRemovedArray<string>

The tools the agent lost.

DataState

A state of the session data: whether more of it can still arrive.

This type has these values:

DATA_STATE_UNSPECIFIED
DATA_STATE_SESSION_ACTIVE
DATA_STATE_SETTLING
DATA_STATE_SETTLED

DataStatus

The status of the session data: whether more of it can still arrive. A read returns the data that exists when it runs, so a response can hold only part of the session data in every state.

stateDataState

The state of the session data: whether more of it can still arrive.

To learn more, see DataState.

retryAfterSecondsinteger

The number of seconds to wait before you read again. Set only when state is DATA_STATE_SETTLING, and 0 in every other state.

LogLevel

The level of a log record, as the logs panel on the dashboard shows and filters it. Python and Node.js agents use different level names, such as CRITICAL in Python and FATAL in Node.js. Thus, the level of a record comes from its OpenTelemetry severity number, or from its level name when it has no severity number. Each level has the same meaning for Python and Node.js agents.

This type has these values:

LOG_LEVEL_UNSPECIFIED
LOG_LEVEL_TRACE
LOG_LEVEL_DEBUG
LOG_LEVEL_INFO
LOG_LEVEL_WARN
LOG_LEVEL_ERROR
LOG_LEVEL_FATAL

LogRecord

A log record that an agent of a session exported.

idstring

The ID of the record. It is the same on every read.

timestamptimestamp

When the record was logged.

levelLogLevel

The level, mapped onto the LogLevel values.

To learn more, see LogLevel.

severityTextstring

The name of the level, as the agent logged it, such as WARN or CRITICAL.

loggerstring

The logger that wrote the record (its logger.name attribute).

messagestring

The text of the record. A structured logger puts the text in the event, message, or msg field of its body. When a structured body has none of these fields, this field holds the full body as JSON.

bodyFieldsMap<string, any>

The fields of a structured log body, other than the message. Empty for a plain text body.

attributesMap<string, any>

The attributes of the record, typed and nested as the agent recorded them. They include its resource and scope attributes. When an attribute has two values, the value of the record is used. An integer larger than 2^53 or smaller than -2^53 is a decimal string. Bytes are base64.

traceIdstring

The ID of the trace that the record was logged in, as lowercase hex. Empty when the record was logged outside a trace. With spanId, it links the record to its span in GetSessionTraces.

spanIdstring

The ID of the span that the record was logged in, as lowercase hex. Empty when the record was logged outside a span.

Message

A message that a participant spoke, or text added to the conversation.

roleRole

Who the message came from.

To learn more, see Role.

textstring

The text of the message. When the agent recorded the text in several parts, newlines join the parts. When redacted is true, <redaction type="..."/> markers replace the PII in the text.

interruptedboolean

When true, the user interrupted this agent message before it ended.

redactedboolean

When true, PII redaction for the project changed the text.

transcriptConfidencenumber

The speech-to-text confidence of a spoken user message, from 0 to 1.

startedSpeakingAttimestamp

The time that the speaker started to speak. Unset for a message that was not spoken.

stoppedSpeakingAttimestamp

The time that the speaker stopped speaking. Unset for a message that was not spoken.

e2eLatencyMsnumber

The end-to-end latency in milliseconds, from the time that the user stopped speaking to the time that the agent started to respond (the agent's e2e_latency). Set on an agent message. Unset when the agent did not record it.

llmTtftMsnumber

The LLM time to first token in milliseconds (llm_node_ttft). Set on an agent message. Unset when the agent did not record it.

ttsTtfbMsnumber

The TTS time to first byte of audio in milliseconds (tts_node_ttfb). Set on an agent message. Unset when the agent did not record it.

transcriptionDelayMsnumber

The time in milliseconds from the end of the user's speech to its final transcript (transcription_delay). Set on a user message. Unset when the agent did not record it.

endOfTurnDelayMsnumber

The time in milliseconds from the end of the user's speech to the time that the agent decided that the turn ended (end_of_turn_delay). Set on a user message. Unset when the agent did not record it.

onUserTurnCompletedDelayMsnumber

The time in milliseconds that the agent spent in its on_user_turn_completed callback (on_user_turn_completed_delay). Set on a user message. Unset when the agent did not record it.

MetricHistogram

A summary of the values that a histogram point recorded.

countint64

The number of values recorded.

sumnumber

The sum of the values. Unset when the agent did not record it.

minnumber

The minimum value. Unset when the agent did not record it.

maxnumber

The maximum value. Unset when the agent did not record it.

bucketBoundsArray<number>

The upper bounds of the histogram buckets. bucketCounts has one more count than bucketBounds. bucketCounts[0] counts the values up to bucketBounds[0]. bucketCounts[i] counts the values in (bucketBounds[i-1], bucketBounds[i]]. The last count counts the values above the last bound. Empty for an exponential histogram.

bucketCountsArray<int64>

The number of values in each histogram bucket. See bucketBounds. Empty for an exponential histogram.

MetricKind

The OpenTelemetry data type of a metric point.

This type has these values:

METRIC_KIND_UNSPECIFIED
METRIC_KIND_GAUGE
METRIC_KIND_SUM
METRIC_KIND_HISTOGRAM
METRIC_KIND_EXPONENTIAL_HISTOGRAM

MetricPoint

An OpenTelemetry metric data point that an agent of a session exported. It is the raw metric that the agent exports, so it does not exactly match the metrics panel on the dashboard, which calculates its values from the transcript and traces. Only an agent that exports OpenTelemetry metrics to LiveKit Cloud has points. An agent whose code installs its own MeterProvider exports no metrics to LiveKit Cloud.

namestring

The name of the metric, such as lk.agents.turn.e2e_latency or gen_ai.client.token.usage. Several metrics with the same attributes can have one name. See GetSessionMetrics.

unitstring

The unit of the metric, as the agent declared it, such as s or {token}. Empty when the agent declared no unit.

kindMetricKind

Which kind of metric the point carries, and so which field of data is set.

To learn more, see MetricKind.

startTimetimestamp

The start of the interval that the point covers. An agent exports every 30 seconds, so a sum or histogram covers the time since its previous export. Unset for a gauge.

endTimetimestamp

The end of the interval, and the moment a gauge was measured.

attributesMap<string, any>

The attributes of the point, typed and nested as the agent recorded them. They include its resource and scope attributes, such as room_id, job_id, lk.agent_name, and the model_name of the model. When an attribute has two values, the value of the point is used. When a session has two agents, the resource attributes can be those of the other agent. An integer larger than 2^53 or smaller than -2^53 is a decimal string. Bytes are base64.

histogramMetricHistogram

The summary of a histogram or exponential histogram. Set when kind is METRIC_KIND_HISTOGRAM or METRIC_KIND_EXPONENTIAL_HISTOGRAM.

At most one of histogram and value is set.

To learn more, see MetricHistogram.

valuenumber

The value of a gauge or sum. Set when kind is METRIC_KIND_GAUGE or METRIC_KIND_SUM.

At most one of histogram and value is set.

RecordingFileType

The type of recording that GetSessionRecordingURL returns. To get the conversation of a session as typed items, use GetSessionTranscript.

This type has these values:

RECORDING_FILE_TYPE_UNSPECIFIED
RECORDING_FILE_TYPE_AUDIO
RECORDING_FILE_TYPE_CHAT_HISTORY

Role

The sender of a transcript message.

This type has these values:

ROLE_UNSPECIFIED
ROLE_USER
ROLE_AGENT
ROLE_SYSTEM
ROLE_DEVELOPER

Span

A unit of work in the trace of a session, such as an agent turn or an LLM request.

spanIdstring

The ID of the span, as lowercase hex.

traceIdstring

The trace ID of the span, as lowercase hex.

parentSpanIdstring

The ID of the parent span, as lowercase hex. Empty for a root span. The dashboard also shows a span as a root when its parent is not one of the spans of the session.

namestring

The span name, as the agent recorded it.

startTimetimestamp

When the span started.

endTimetimestamp

When the span ended.

kindSpanKind

Where the span sits in the call: internal, server, client, producer, or consumer.

To learn more, see SpanKind.

statusSpanStatus

Whether the span succeeded.

To learn more, see SpanStatus.

statusMessagestring

Why the span failed; set when status is error.

attributesMap<string, any>

The attributes of the span, typed and nested as the agent recorded them. They include its resource and scope attributes, such as lk.agent_name. When an attribute has two values, the value of the span is used. An integer larger than 2^53 or smaller than -2^53 is a decimal string. Bytes are base64.

eventsArray<SpanEvent>

The events the agent recorded on the span.

To learn more, see SpanEvent.

SpanEvent

An event with a timestamp that a span recorded, such as an exception.

timestamptimestamp

When the event happened.

namestring

The event name, as the agent recorded it.

attributesMap<string, any>

The attributes of the event, typed and nested as the agent recorded them.

SpanKind

The OpenTelemetry kind of a span.

This type has these values:

SPAN_KIND_UNSPECIFIED
SPAN_KIND_INTERNAL
SPAN_KIND_SERVER
SPAN_KIND_CLIENT
SPAN_KIND_PRODUCER
SPAN_KIND_CONSUMER

SpanStatus

The OpenTelemetry status code of a span.

This type has these values:

SPAN_STATUS_UNSPECIFIED
SPAN_STATUS_OK
SPAN_STATUS_ERROR

ToolCall

The agent calling a tool.

namestring

The tool the agent called.

callIdstring

The ID of the call. The ToolResult of the call has the same callId.

argumentsstring

The arguments of the call, as a JSON string.

ToolResult

The output a tool returned for a ToolCall.

namestring

The tool that returned the output.

callIdstring

The callId of the ToolCall that this result answers.

outputstring

What the tool returned.

isErrorboolean

When true, the tool failed, and output describes the error.

TranscriptItem

An entry in the conversation of a session. Exactly one of message, toolCall, toolResult, agentHandoff, and configUpdate is set.

idstring

The ID of the item, as the agent assigned it (item_...).

timestamptimestamp

The time of the item. For a message, the time that its speaker started to speak, or else the time that the agent created it. For other items, the time that the agent recorded it. Items are ordered by the time that the agent recorded them, so the timestamp of a message can be earlier than the timestamp of the item before it.

agentHandoffTranscriptItem.AgentHandoff

The session passing from one agent to another.