Session analytics

Overview

Use the lk analytics session commands to read the observability data of your deployed agent: the transcripts, logs, traces, metrics, and recordings of its sessions. A coding agent can run these commands to find the problems that users have with your agent, such as slow turns, tool errors, and interruptions, and then change your agent code to fix them. You can also use them to debug one session from the terminal.

These commands require LiveKit CLI v2.19.4 or later. To update the CLI, see Updates.

These commands need user authentication. Sign in with lk cloud auth --user-auth, and pass --user-auth to each command. The session list and session get commands also run with an API key and --experimental, but that path is deprecated. The commands use the project from the --project option or your default project. To install the CLI, see Install the CLI.

lk analytics <command> [options]

Subcommands:

• session: List and inspect sessions.

Options for analytics:

• --experimental: Use the deprecated API-key analytics (not needed with --user-auth).

Rate limits

The LiveKit Cloud API limits the number of requests to each project per minute. The limit depends on the plan of the project. Each lk analytics command makes one or more requests.

When a project goes over its limit, the API returns status 429. Wait, and then run the command again.

Find a session

These commands find the sessions in a project, and list the participants and events of a session.

List

List the sessions in a project, most recent first.

lk analytics session list [options]

Options for session list:

• --json (alias -j): Output as JSON.
• --limit VALUE: Maximum number of sessions to return. Default: 10.
• --page VALUE: Page number (starts at 0); deprecated, API-key only (--user-auth pages with --cursor).
• --since DURATION: List sessions started within the last DURATION, such as 90m, 6h, 14d or 2w (default 14d unless --start is set); can't be used with --start or --end.
• --start YYYY-MM-DD: List sessions started on or after YYYY-MM-DD (UTC).
• --end YYYY-MM-DD: List sessions started before YYYY-MM-DD (UTC, exclusive); requires --start.
• --cursor CURSOR: Page CURSOR from a prior --json listing (requires --user-auth).
• --status STATUS: List sessions in STATUS (active or closed); repeatable (requires --user-auth).
• --room PREFIX: List sessions whose room name starts with PREFIX (case-sensitive; requires --user-auth).
• --tag TAG: List sessions carrying TAG; repeatable, matches any (requires --user-auth).
• --sort-order ORDER: Order by start time: ORDER asc or desc, default desc (requires --user-auth).

Examples

List active sessions in rooms whose names start with support-:

lk analytics session list --status active --room support- --user-auth

List sessions from the last 6 hours as JSON:

lk analytics session list --since 6h --json --user-auth

Get

Get the details of a session.

lk analytics session get [options] SESSION_ID

Options for session get:

• --json (alias -j): Output as JSON.

Participants

List the participants in a session.

lk analytics session participant list [options] SESSION_ID

Options for session participant list:

• --json (alias -j): Output as JSON.
• --sort-by FIELD: Order by FIELD: joined or left, default joined.
• --sort-order ORDER: Order direction: ORDER asc or desc, default desc.
• --limit VALUE: Maximum number of participants to read (the server caps a page's size). Default: 50.

Events

Print the events of a session, such as participants joining and leaving. To print other events, such as tracks being published, pass --type or --participant. LiveKit keeps events for 60 days.

lk analytics session events SESSION_ID [--type TYPE ...] [--participant PA_ID] [--sort-order asc|desc]

Options for session events:

• --json (alias -j): Output as JSON.
• --type TYPE: Print only events of TYPE, such as participant_joined or track_published; repeatable, matches any (default the dashboard's seven, or with --participant its eleven participant types).
• --participant PA_ID: Print only the events of the participant session PA_ID, as lk analytics session participant list prints it; with no --type, the dashboard's eleven participant types, track events included.
• --sort-order ORDER: Order by time: ORDER asc or desc, default asc.
• --limit VALUE: Maximum number of events to read, reading every page up to it (default one page of the server's default size).

Agent insights

These commands read the Agent insights data for a session. They need the Admin role on the project.

This data exists only for sessions that run while agent observability is on. Projects you create with the CLI have it off unless you pass --user-data-recording. To turn it on for a project, run lk project update PROJECT_ID --user-data-recording --user-auth. By default, LiveKit deletes this data 30 days after a session ends. To learn more, see Retention window.

Data for a session can keep arriving for a few minutes after the session ends. While the data can still change, the transcript, logs, traces, and metrics commands print a note that tells you when to read the data again. With --json, the dataStatus field shows the state of the data.

Transcript

lk analytics session transcript [options] SESSION_ID

Options for session transcript:

• --json (alias -j): Output as JSON.
• --limit VALUE: Maximum number of transcript items to read, reading every page up to it (default one page of the server's default size).

Recording

Print a URL for the audio recording or chat history of a session. The URL is valid for 15 minutes. Add -o to also download the file. If the recording isn't ready, the command exits with code 75, and a script can try again later.

lk analytics session recording SESSION_ID [--type audio|chat-history] [-o FILE|DIR]

Options for session recording:

• --json (alias -j): Output as JSON.
• --type TYPE: TYPE of recording: audio (the conversation's audio, Ogg) or chat-history (the agent's record of the conversation, JSON). Default: audio.
• --output FILE (alias -o): Also download the recording to FILE, replacing it if it exists, or into a directory as SESSION_ID-audio.ogg or SESSION_ID-chat-history.json, numbered rather than replacing a file.

Examples

Download the audio recording to the working directory:

lk analytics session recording SESSION_ID -o . --user-auth

Download the chat history:

lk analytics session recording SESSION_ID --type chat-history -o . --user-auth

Logs

Print the agent's logs for a session.

lk analytics session logs SESSION_ID [--log-level LEVEL ...] [--sort-order asc|desc]

Options for session logs:

• --json (alias -j): Output as JSON.
• --log-level LEVEL: Print only records at LEVEL: trace, debug, info, warn, error or fatal; repeatable, matches any (default every record).
• --sort-order ORDER: Order by time: ORDER asc or desc, default asc.
• --limit VALUE: Maximum number of records to read, reading every page up to it (default one page of the server's default size).

Examples

Print only the warning and error logs:

lk analytics session logs SESSION_ID --log-level warn --log-level error --user-auth

Traces

Print the trace spans of a session as a tree.

lk analytics session traces [options] SESSION_ID

Options for session traces:

• --json (alias -j): Output as JSON.
• --limit VALUE: Maximum number of spans to read, reading every page up to it (default one page of the server's default size).

Metrics

Print the metric points that the agents in the session exported. These raw metrics don't always match the metrics panel in the dashboard. The panel uses the transcript and traces.

lk analytics session metrics SESSION_ID [--name NAME ...]

Options for session metrics:

• --json (alias -j): Output as JSON.
• --name NAME: Print only the points of the metric named NAME, matched exactly, such as lk.agents.turn.e2e_latency; repeatable (default every metric).
• --limit VALUE: Maximum number of points to read, reading every page up to it (default one page of the server's default size).

Examples

Print one metric by name:

lk analytics session metrics SESSION_ID --name lk.agents.turn.e2e_latency --user-auth