Docs
Status
OverviewQuickstartSetup promptsThe core loopAuthenticationChatAgentOverviewModelsThe waterfallPlansAdding modelsData controlsContent moderationKYCResellersOpenAI compatibilityEmbeddingsAnthropic APIGemini APIErrorsIntegrate the gatewayCost APIRequest log APITraces and sessionsAnalyze tracesAccount APICoding agentsSwitch gatewaysMoving from HeliconeCredits & billingSpend & intelligenceSpend APITelemetryBecome a providerProvider guideAPI reference

Get started

  • Overview
  • Quickstart
  • Setup prompts
  • The core loop
  • Authentication

Experiential Agent

  • Chat
  • Agent

Guides

  • Overview
  • Models
  • The waterfall
  • Plans
  • Adding models
  • Data controls
  • Content moderation
  • KYC
  • Resellers
  • OpenAI compatibility
  • Embeddings
  • Anthropic API
  • Gemini API
  • Errors

Integrations

  • Integrate the gateway
  • Cost API
  • Request log API
  • Traces and sessions
  • Analyze traces
  • Account API
  • Coding agents
  • Switch gateways
  • Moving from Helicone

Billing & usage

  • Credits & billing
  • Spend & intelligence
  • Spend API
  • Telemetry

Providers

  • Become a provider
  • Provider guide

Reference

  • API reference

Integrations

Traces and sessions

See an agent run as one trace with a tree of steps. Add headers to the calls you already make, send your own spans with OpenTelemetry or a Langfuse SDK, or both.

How a run becomes a trace

An agent run is many requests: model calls, tool calls between them, and subagents. Observability shows each run as one trace and one session. Three sources add up and never replace each other: headers on your model calls, tool calls and subagents we infer from your traffic, and spans you send yourself. Read the result with the Request log API or the trace tools.

1. Headers on the calls you already make

No SDK is needed. Add any of these to the model calls that go through the gateway. A header always wins over the same fact in the body. Claude Code and Codex need nothing: their own session headers already link their turns and subagents.

FactHeadersOr in the request body
Session idX-Explabs-Session-Id, Helicone-Session-Id, x-session-id, x-litellm-session-id, baggage: gen_ai.conversation.id=...metadata.session_id, metadata["gen_ai.conversation.id"]
Parent sessionX-Explabs-Parent-Session-Id, x-parent-session-idmetadata.parent_session_id
Session nameX-Explabs-Session-Name, Helicone-Session-Namemetadata.session_name
Place in your tracetraceparent (W3C)metadata.traceparent
Trace nameX-Explabs-Trace-Namemetadata.trace_name
Step nameX-Explabs-Span-Name, X-Explabs-Step-Name, X-Explabs-Observation-Namemetadata.span_name
Step path, like /plan/research/search-1X-Explabs-Step-Path, X-Explabs-Session-Path, Helicone-Session-Pathmetadata.step_path
End userX-Explabs-User-Id, Helicone-User-Idmetadata.end_user, metadata.user_id, safety_identifier, user
TagsX-Explabs-Tags: {"env":"prod"}metadata.tags (an object, a JSON object string, or a list of "key:value")
One call with a session, a step path and tags
curl https://api.experientiallabs.ai/v1/chat/completions \
-H "Authorization: Bearer $EXPLABS_API_KEY" \
-H "X-Explabs-Session-Id: run-42" \
-H "X-Explabs-Step-Path: /plan/research/search-1" \
-H 'X-Explabs-Tags: {"env":"prod","feature":"support"}' \
-H "Content-Type: application/json" \
-d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"hi"}]}'
  • Limits: ids up to 256 characters, names up to 200, a path up to 512 characters and 32 steps, and 16 tags. A body value that does not fit is skipped, and the request is never refused for it. A malformed X-Explabs-Tags header is still a 400.
  • Every request has a session. If you send none, it is filed under the conversation we recognize, or else under its own trace.
  • Every gateway request is one span. Its span id comes from the request id, so it is the same in Observability, in every API answer and in an export to your own Langfuse. A call without traceparent starts its own trace.

2. Tool calls and subagents we infer

When a response asks for tool calls and the next request carries their results, we add one tool span per call with the name, arguments, result and a duration equal to the gap between the two. These spans are marked inferred (inf: 1 in an API answer) because the gap also holds any other work your code did. Subagents come from Claude Code's agent id or a nested traceparent. Inference runs only on requests whose content is stored. When you send your own tool spans, yours are the truth.

Inference and search depend on our capture pipeline. Until it is running for your deployment, you get the request rows, sessions and headers above, but no inferred tool spans.

3. Your own spans

Spans you send land in the same trace as our model spans when they share the trace id. Our spans add exact tokens, cost and fallback detail to yours and never replace them. Use your organization's xpl_ key. Both ways in take it.

Method and pathWhat it takes
POST /v1/tracesOTLP over HTTP, protobuf (application/x-protobuf) or JSON, optionally gzip.
POST /api/otlp/v1/tracesThe same, for setups that only route /api paths.
POST /api/public/otel/v1/tracesThe same, at Langfuse's OpenTelemetry path (Langfuse Python SDK v3).
POST /api/public/ingestionThe Langfuse batch ingestion API. Answers 207 with successes and errors for each event, as Langfuse does.
GET /api/public/projectsThe project your key belongs to (the project id is your organization id), for the Langfuse SDK's auth check.
GET /api/public/health{"status": "OK"}. No key needed.

Send the key as Authorization: Bearer xpl_..., as x-api-key: xpl_..., or as Authorization: Basic base64(public:secret), the Langfuse form, where the secret is your xpl_ key and the public key can be anything. Spans always go to the key's own organization. gRPC is not supported. Use OTLP over HTTP. The base URL is https://api-pr-902980.preview.experientiallabs.ai.

What we store

  • Span names, ids, parents, times, status, model and token counts are always stored.
  • Inputs, outputs, prompts, tool arguments and tool results are stored only while your organization stores prompt content and zero data retention is off. When storage is off we remove them as the span arrives. You still see the shape and timing of the trace.
  • A cost you report on your own span is kept as customer.cost_usd. It is never added to session or trace totals, because our span of the same call carries the exact charged cost.

Which attributes we read

FactAttributes (the first one found wins)
Sessionsession.id, langfuse.session.id, gen_ai.conversation.id, explabs.session.id
End useruser.id, langfuse.user.id, enduser.id
Modelgen_ai.response.model, gen_ai.request.model, langfuse.observation.model.name, llm.model_name, ai.model.id, model
Tokensgen_ai.usage.input_tokens and output_tokens, llm.token_count.*, ai.usage.*, input_tokens and output_tokens, langfuse.observation.usage_details
Tagslangfuse.trace.tags, tag.tags, explabs.tags (lists of key:value or names), explabs.tag.<key>
Step pathexplabs.step_path

A span with no session is filed under its trace. If one span of a trace names the session, later spans of that trace join it, even in later batches.

Limits and errors

Limit (per organization)ValueWhen you pass it
Request body4 MiB as sent, 16 MiB after gzip413
Spans in one request2,000The rest are rejected through OTLP partial success (a 413 per Langfuse event).
Requests50 a second, bursts of 100429 with Retry-After
Spans2,000 a second, bursts of 10,000429 with Retry-After
Requests in progress at once4429 with Retry-After
StatusMeaning
400 invalid_payloadThe body is not an OTLP export or a Langfuse batch.
401 unauthorizedThe key is missing, unknown or revoked. A customer-plan key cannot send spans.
413 payload_too_largeOver 4 MiB as sent or 16 MiB inflated.
415 unsupported_media_type, unsupported_encodingNot protobuf or JSON, or not identity, gzip or deflate.
429 rate_limitedOver a limit. Wait the Retry-After seconds.
503 ingest_unavailableWe could not store the spans. Retry after Retry-After.

Framework recipes

Replace xpl_... with your key. Every OTLP exporter reads these standard variables, and the recipes below use them:

OpenTelemetry variables
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.experientiallabs.ai"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer xpl_..."

To put our model span inside your own span, send the W3C traceparent header on the model call. OpenTelemetry's HTTP instrumentation does this for you.

Vercel AI SDK

instrumentation.ts
import { registerOTel } from "@vercel/otel";
export function register() {
registerOTel({ serviceName: "my-agent" });
}
Turn telemetry on for each call
const result = await generateText({
model,
prompt,
experimental_telemetry: { isEnabled: true, functionId: "support-agent" },
});

Mastra

Use the custom provider and turn logs off. We take traces only. Install @opentelemetry/exporter-trace-otlp-proto.

typescript
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { OtelExporter } from "@mastra/otel-exporter";
export const mastra = new Mastra({
observability: new Observability({
configs: {
otel: {
serviceName: "my-agent",
exporters: [
new OtelExporter({
provider: {
custom: {
endpoint: "https://api.experientiallabs.ai/v1/traces",
protocol: "http/protobuf",
headers: { "x-api-key": process.env.EXPLABS_API_KEY! },
},
},
signals: { traces: true, logs: false },
}),
],
},
},
}),
});

LangGraph and LangChain

Either keep the Langfuse callback handler and change its host (below), or use OpenInference. Put the session on the spans with session.id.

pip install openinference-instrumentation-langchain opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
from openinference.instrumentation.langchain import LangChainInstrumentor
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
LangChainInstrumentor().instrument(tracer_provider=provider)

OpenAI Agents SDK

Add an OpenTelemetry processor through OpenInference, with the variables above and the same tracer provider.

pip install openinference-instrumentation-openai-agents
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)

Claude Agent SDK and Claude Code

Claude Code exports spans when tracing is on. Tracing is a beta and off by default. CLAUDE_CODE_PROPAGATE_TRACEPARENT makes each of our model spans nest under Claude Code's own span. Prompts and tool details stay out of its spans unless you also set OTEL_LOG_USER_PROMPTS=1, OTEL_LOG_TOOL_DETAILS=1 and OTEL_LOG_TOOL_CONTENT=1.

bash
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.experientiallabs.ai/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer xpl_..."
export CLAUDE_CODE_PROPAGATE_TRACEPARENT=1

Plain OpenTelemetry

Set the variables above and use any OTLP over HTTP exporter. Send session.id on your root span (or every span) to group runs into sessions.

Langfuse SDKs

Keep your Langfuse code and change two settings. LANGFUSE_PUBLIC_KEY can stay as it is. The host variable is LANGFUSE_HOST, LANGFUSE_BASE_URL or LANGFUSE_BASEURL, depending on the SDK version. Langfuse score-create events become scores on the span or trace they name.

bash
export LANGFUSE_HOST="https://api.experientiallabs.ai"
export LANGFUSE_SECRET_KEY="xpl_..."
We serve Langfuse tracing only: ingestion, the OpenTelemetry path, health and projects. Langfuse prompt management and its dataset API are not served, so code that calls them still needs Langfuse for those.
PreviousRequest log APINextAnalyze traces