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.
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
SELECTonly (joins, subqueries,WITHandUNIONwork). Table functions,systemtables,SETTINGS,FORMAT, comments and a second statement are refused with 400sql_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.
truncatedis 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.
| Feature | Routes under /api/orgs/{org_id} | Who can call them |
|---|---|---|
| Score configs | GET, 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. |
| Scores | GET, 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 queues | GET, POST /annotation-queues, PATCH, DELETE /annotation-queues/{id}, GET, POST /annotation-queues/{id}/items | An 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. |
| Datasets | GET, POST /datasets, /datasets/{id}/items, GET /datasets/{id}/export | Members and org keys. Export is JSON lines. |
| Dataset runs | POST /datasets/{id}/runs/estimate, POST, GET /datasets/{id}/runs | Admins and org keys. A run spends credits, so you price it first. |
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.
| Field | Meaning |
|---|---|
| name | What people see. 1 to 80 characters, unique in the organization (case ignored). |
| kind | boolean (a yes or no question) or rubric (levels from lowest to highest, 2 to 10). |
| question | What the judge reads. 1 to 1,000 characters. |
| threshold | The tag fires when its score reaches this. Default 0.5. |
| scope | llm_call, tool_call or session. |
| filters | Limit a tag to some keys, models or request tags, and a sample rate (default 1, which is every session). |
| judge_model | Any catalog model. Default clef. |
| status | active or paused. An organization can have 32 active tags. |
| alert, webhook | Email 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}/scores | How many calls were scored and fired per hour or day, and the scores with reasons. |
| PUT /budget | Calls per second and an optional monthly spend cap for the judge. |
| POST /{id}/backfill/estimate, POST /{id}/backfills | Score past traffic (at most 90 days): get a price estimate first, then start it with the token it returns. |
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.
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.export EXPLABS_API_KEY=xpl_...explabs-traces sessions list --since 2h --status failedexplabs-traces sessions get run-42explabs-traces --json traces get 4bf92f35...explabs-traces requests search "timeout" --since 1dexplabs-traces requests tail --model gpt-6-lunaexplabs-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 withrequests get --bodyorsessions 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.aiunless you setEXPLABS_API_URL. The organization comes from your key unless you setEXPLABS_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.