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

Analyze traces

Ask your own questions of your traces with SQL, grade them with scores and review queues, build datasets from real traffic, tag calls automatically, and do all of it from a terminal or an agent.

Trace SQL

POST /api/orgs/{org_id}/trace-sql runs one read-only SELECT over your own requests, spans, sessions and scores. The answer is {columns, rows, truncated, elapsed_ms}. GET .../trace-sql/schema lists the tables and columns. Any key of your organization can call both.

Count requests by model
curl -X POST "https://api-pr-902980.preview.experientiallabs.ai/api/orgs/$ORG_ID/trace-sql" \
-H "Authorization: Bearer $EXPLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "select model, count() as n from requests group by model order by n desc", "limit": 100}'
  • One SELECT only (joins, subqueries, WITH and UNION work). Table functions, system tables, SETTINGS, FORMAT, comments and a second statement are refused with 400 sql_not_allowed, and the error names the construct.
  • Every table is limited to your organization, so no query can read another organization's rows.
  • Queries have a time limit and row, byte and memory limits, and SQL has a stricter rate limit than other reads. truncated is true when the row limit cut the answer.

Scores, review queues and datasets

A score is a judgement about a request, a session or a span: from a person, from your code, or from a judge model. A score is not content, so you can score a request that was not stored. Langfuse score-create events sent to /api/public/ingestion become scores too.

FeatureRoutes under /api/orgs/{org_id}Who can call them
Score configsGET, POST /score-configs, PATCH /score-configs/{id}Any member reads. An admin writes. A config fixes a name and a type: a number with bounds, a boolean or a category.
ScoresGET, POST /scores, GET /scores/summary, DELETE /scores/{id}Members and org keys. A score points at one request, session or span. Delete is for admins.
Review queuesGET, POST /annotation-queues, PATCH, DELETE /annotation-queues/{id}, GET, POST /annotation-queues/{id}/itemsAn admin creates a queue and names the score configs it asks for. A member or key adds items. Claiming the next item and completing it need a signed-in person.
DatasetsGET, POST /datasets, /datasets/{id}/items, GET /datasets/{id}/exportMembers and org keys. Export is JSON lines.
Dataset runsPOST /datasets/{id}/runs/estimate, POST, GET /datasets/{id}/runsAdmins and org keys. A run spends credits, so you price it first.
Give a request a score
curl -X POST "https://api-pr-902980.preview.experientiallabs.ai/api/orgs/$ORG_ID/scores" \
-H "Authorization: Bearer $EXPLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target": {"kind": "request", "id": "'"$REQUEST_ID"'"}, "name": "helpful", "value": 0.9, "comment": "Answered in one step"}'
  • Dataset items copy stored content only. A request becomes its messages and tools as input and its reply as the expected output. A session becomes its first task and its final answer. Anything not stored is skipped with the reason not_stored.
  • Limits: 100 datasets, 5,000 items each, 512 KiB an item and 512 MiB per organization.
  • A dataset run sends each item as a real request on a key named for the run, so it costs credits. It stops when cancelled, when you run out of credits, or at twice its estimate.
  • Turning storage off or deleting stored content also removes dataset items and run outputs copied from traffic, and the comments and category values of scores. Items you wrote by hand stay.

Trace tags

A trace tag is a question you ask about your traffic, such as "Did the assistant stop before finishing the task?" or a 0 to 1 rubric. When tagging is running, a judge model answers it for calls as they arrive, and the answers show on requests, sessions and charts. You manage tags on the Quality page, or with the API using your organization's key.

FieldMeaning
nameWhat people see. 1 to 80 characters, unique in the organization (case ignored).
kindboolean (a yes or no question) or rubric (levels from lowest to highest, 2 to 10).
questionWhat the judge reads. 1 to 1,000 characters.
thresholdThe tag fires when its score reaches this. Default 0.5.
scopellm_call, tool_call or session.
filtersLimit a tag to some keys, models or request tags, and a sample rate (default 1, which is every session).
judge_modelAny catalog model. Default clef.
statusactive or paused. An organization can have 32 active tags.
alert, webhookEmail when the fire rate passes a limit, or a signed POST on each fire. Both are off by default.
Route (under /api/orgs/{org_id}/trace-tags)What it does
GET /, POST /List every tag with its last 7 days, or create one.
GET, PATCH, DELETE /{id}Read, edit or delete a tag. Deleting removes its scores.
GET /{id}/rates, GET /{id}/scoresHow many calls were scored and fired per hour or day, and the scores with reasons.
PUT /budgetCalls per second and an optional monthly spend cap for the judge.
POST /{id}/backfill/estimate, POST /{id}/backfillsScore past traffic (at most 90 days): get a price estimate first, then start it with the token it returns.
Tags can be created before tagging runs, but nothing scores until the tagging service is running for your deployment. If it is not, a tag shows no results. Tagging also reads only content you store: with storage off, zero data retention required, or a request routed under zero data retention, nothing is scored.

What it costs

Each judge call is an ordinary request on a key named Trace tagging that we create in your organization. It draws from your credits at the judge model's normal rate and follows your limits and data controls. The default judge, Clef, bills input tokens only. Tagging pauses, and never retries in a loop, when you are out of credits, need verification, reach your monthly cap, or have storage off.

Alerts and webhooks

A webhook posts JSON to a public https URL. Each delivery carries X-Explabs-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, X-Explabs-Event (tag.fired, tag.alert or tag.test) and X-Explabs-Delivery, a unique id to deduplicate on. Compute the HMAC with your signing secret, compare in constant time, and refuse a timestamp more than 5 minutes old. A failed delivery is retried with growing delays and set aside after 8 attempts.

The command line and the MCP server

explabs-traces reads the same API from a terminal or an agent. explabs-traces-mcp is a stdio MCP server with the same reads as tools. Both use an xpl_ key of your organization from EXPLABS_API_KEY.

These tools are not published for install yet. They ship as console scripts of the Experiential Labs platform Python package, and there is no pip install for them today. Everything they do is also available over the HTTP routes on this page and on the Request log API page, which is what the agent prompt on Setup prompts uses.
bash
export EXPLABS_API_KEY=xpl_...
explabs-traces sessions list --since 2h --status failed
explabs-traces sessions get run-42
explabs-traces --json traces get 4bf92f35...
explabs-traces requests search "timeout" --since 1d
explabs-traces requests tail --model gpt-6-luna
explabs-traces sql "select path, count() from requests group by path"
  • Lists print the next cursor on standard error (inside the JSON with --json). Bodies are fetched only with requests get --body or sessions export --bodies.
  • Exit codes: 0 ok, 1 other failure, 2 bad request, 3 not found, 4 authentication, 5 rate limited.
  • The base URL is https://api-pr-902980.preview.experientiallabs.ai unless you set EXPLABS_API_URL. The organization comes from your key unless you set EXPLABS_ORG_ID.
  • MCP tools: list_traces, get_trace, list_sessions, get_session_skeleton, list_requests, search_requests, get_request, get_request_body, run_trace_sql, add_score, add_to_dataset.
PreviousTraces and sessionsNextAccount API