OpenTelemetry traces

ElevenLabs Agents can export conversations as OpenTelemetry traces encoded as OTLP JSON (resourceSpans). Forward them to Datadog, Grafana Tempo, Honeycomb, or any backend that ingests OTLP.

Overview

Export traces from three surfaces. All three share the same trace ID per conversation and elevenlabs.* attribute naming. Span shape and timing differ between post-call/GET (transcript-based) and monitoring (event-based).

Export surfaces

Choosing a surface

• Every completed call in your data warehouse: post-call webhook
• One-off export or repair: GET conversation with format=opentelemetry
• Live supervisor UI or alerting: monitoring WebSocket
• Full fidelity timeline after the fact: post-call webhook or GET conversation
• Tool, MCP, or guardrail events as they happen: monitoring WebSocket

Use traceId or elevenlabs.conversation_id to join data across surfaces. Combine monitoring for live operations, webhooks for durable analytics, and GET for backfill.

You need an OTLP-capable collector or observability vendor for every surface. Post-call webhooks require a workspace webhook endpoint. The GET API and monitoring WebSocket each have their own API key scopes and setup; see the sections below.

Post-call webhook

After a conversation finishes, ElevenLabs sends a POST request when a post-call webhook is configured, events includes transcript, and transcript_format is opentelemetry.

The webhook type is post_call_transcription_otel (not post_call_transcription, which returns JSON transcripts).

Webhook payload

1
{
2
  "type": "post_call_transcription_otel",
3
  "event_timestamp": 1700000000,
4
  "data": {
5
    "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
6
    "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
7
    "otlp_traces": {
8
      "resourceSpans": []
9
    }
10
  }
11
}

Enable OpenTelemetry transcripts

Delivery

Trace shape

Each delivery is one complete trace: a root span plus children.

elevenlabs.conversation
├── elevenlabs.recv.user_transcript
├── elevenlabs.recv.agent_response
│   └── elevenlabs.tool.{name}
└── ...

Timing comes from transcript time_in_call_secs and call metadata. The root span sets elevenlabs.source = post_call_webhook and status ERROR when the call did not end with a normal client disconnect.

GET conversation

Request OpenTelemetry format on Get conversation to receive the same otlp_traces object as the post-call OpenTelemetry webhook, plus the full conversation model.

1
GET /v1/convai/conversations/{conversation_id}?format=opentelemetry

Requires an API key with CONVAI_READ. With format=json (default), otlp_traces is omitted.

1
{
2
  "conversation_id": "conv_9001k1zph3fkeh5s8xg9z90swaqa",
3
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
4
  "status": "done",
5
  "transcript": [],
6
  "otlp_traces": {
7
    "resourceSpans": []
8
  }
9
}

1
import os
2
3
from dotenv import load_dotenv
4
from elevenlabs import ElevenLabs
5
6
load_dotenv()
7
elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))
8
9
conversation = elevenlabs.conversational_ai.conversations.get(
10
    conversation_id="conv_9001k1zph3fkeh5s8xg9z90swaqa",
11
    format="opentelemetry",
12
)
13
14
otlp_traces = conversation.otlp_traces

Expected span names include elevenlabs.conversation, elevenlabs.recv.user_transcript, and elevenlabs.recv.agent_response.

Monitoring WebSocket

Stream OpenTelemetry trace data as OTLP JSON while a conversation is in progress. Each message is a small resourceSpans batch, not one end-of-call trace.

wss://api.elevenlabs.io/v1/convai/conversations/{conversation_id}/monitor?events_format=opentelemetry

Authentication requires CONVAI_WRITE, xi-api-key (or Authorization), and EDITOR access on the agent workspace. Connect after the conversation starts.

Session protocol

1. Connect with authentication headers.
2. Receive {"type": "connected"}.
3. Receive a root span batch (elevenlabs.conversation, elevenlabs.source = monitoring).
4. Receive cached history (around the last 100 events), then {"type": "history_complete"}.
5. Receive live span batches as events occur.

With events_format=json (default), the WebSocket returns raw client events instead of resourceSpans. Control commands match Real-time monitoring.

Trace shape

elevenlabs.conversation
├── elevenlabs.turn.0
│   ├── elevenlabs.event.user_transcript
│   └── elevenlabs.tool.{name}
└── elevenlabs.turn.1

Structured events map to dedicated attributes (for example elevenlabs.user.text, elevenlabs.agent.text). Unknown events use elevenlabs.event.data with truncated JSON.

Example connection

1
import WebSocket from "ws";
2
3
const ws = new WebSocket(
4
  "wss://api.elevenlabs.io/v1/convai/conversations/conv_9001k1zph3fkeh5s8xg9z90swaqa/monitor?events_format=opentelemetry",
5
  {
6
    headers: {
7
      "xi-api-key": process.env.ELEVENLABS_API_KEY!,
8
    },
9
  }
10
);
11
12
ws.on("message", (raw) => {
13
  const msg = JSON.parse(raw.toString());
14
  if (msg.type === "connected" || msg.type === "history_complete") return;
15
16
  if (msg.resourceSpans) {
17
    forwardToCollector({ resourceSpans: msg.resourceSpans });
18
  }
19
});

OTLP JSON structure

OpenTelemetry traces from all surfaces share the same OTLP JSON batch layout:

1
{
2
  "resourceSpans": [
3
    {
4
      "resource": {
5
        "attributes": [
6
          { "key": "service.name", "value": { "stringValue": "elevenlabs-convai" } },
7
          {
8
            "key": "elevenlabs.conversation_id",
9
            "value": { "stringValue": "conv_9001k1zph3fkeh5s8xg9z90swaqa" }
10
          }
11
        ]
12
      },
13
      "scopeSpans": [
14
        {
15
          "scope": { "name": "elevenlabs.convai", "version": "1.0.0" },
16
          "spans": [
17
            {
18
              "traceId": "32_hex_chars",
19
              "spanId": "16_hex_chars",
20
              "name": "elevenlabs.recv.agent_response",
21
              "startTimeUnixNano": "1700000000000000000",
22
              "endTimeUnixNano": "1700000001000000000",
23
              "status": { "code": 1 }
24
            }
25
          ]
26
        }
27
      ]
28
    }
29
  ]
30
}

Limitations

• No direct push to your OTLP gRPC endpoint.
• Payloads are JSON shaped like OTLP export, not raw protobuf on the wire.

Related documentation

• Post-call webhooks
• Real-time monitoring