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

Request log API

List and filter your organization's requests, read one with its prompt and response, and read latency and spend. These are the reads behind Observability, and any key of your organization can call them.

Access

Send any xpl_ key of your organization as Authorization: Bearer. Every route here is a GET under https://api-pr-902980.preview.experientiallabs.ai/api and reads only that key's organization. Get its id from GET /api/whoami; another organization's id answers 404.

Any key of your organization can read prompt and response bodies when prompt capture is on. Give a key only to code or agents you would let read your traffic. A key bound to a customer plan cannot call these routes.
RouteReturns
GET /api/whoamiYour key's organization: org_id, org_slug, org_name.
GET /api/orgs/{org_id}/usage/requestsOne page of requests in any order, next_cursor, and live_cursor for new rows.
GET /api/orgs/{org_id}/usage/requests/exportEvery request under the same filters and order, streamed as CSV or JSON lines (format=csv|jsonl). No row limit.
GET /api/orgs/{org_id}/usage/requests/{request_id}One request. With include_body=true, its captured prompt and response as body.
GET /api/orgs/{org_id}/usage/requests/{request_id}/promptThe captured prompt and response alone; 404 when nothing was captured.
GET /api/orgs/{org_id}/usage/requests/{request_id}/attemptsEvery provider dispatch of the request (retries and fallbacks), at most 256.
GET /api/orgs/{org_id}/usage/requests/groupsThe requests grouped by prompt (by=prompt) or by conversation (by=conversation), with each group's totals.
GET /api/orgs/{org_id}/sessionsSessions with their totals, sorted by activity, cost, duration, requests or errors.
GET /api/orgs/{org_id}/sessions/{session_id}One session's totals and the previous and next session; 404 session_not_found.
GET /api/orgs/{org_id}/sessions/{session_id}/skeletonEvery request and span of the session, no bodies, as JSON lines (about 200 bytes each).
GET /api/orgs/{org_id}/sessions/{session_id}/requestsThe session's full request rows in start order, paged.
GET /api/orgs/{org_id}/sessions/{session_id}/turnsEach request's new messages and response, with resent history folded to a count.
GET /api/orgs/{org_id}/sessions/{session_id}/searchText matches inside the session, with highlight offsets.
GET /api/orgs/{org_id}/sessions/{session_id}/exportThe whole session with bodies, streamed as JSON lines.
GET /api/orgs/{org_id}/tracesAgent traces under the same filters.
GET /api/orgs/{org_id}/traces/{trace_id}One trace's span tree as JSON lines; inferred tool spans carry inf=1.
GET /api/orgs/{org_id}/requests/searchRequests whose text matches q, in one time range, with highlighted snippets.
GET /api/orgs/{org_id}/usage/timeseriesRequests, errors, tokens and cost per time bucket, model and lane.
GET /api/orgs/{org_id}/usage/latencyp50 and p95 latency and time to first token over the window.
GET /api/orgs/{org_id}/usage/by-providerThe same totals per provider.
GET /api/orgs/{org_id}/usage/by-labelThe same totals per end-user label.
GET /api/orgs/{org_id}/telemetry-settingscapture_prompt_content: whether prompts and responses are stored.

Reads with a key are limited per organization: about 10 per second with short bursts, and a few at a time. Over the limit, a read answers 429 with Retry-After. Signed-in dashboard use is not counted.

Let an agent read it

The quickest way to use this API is the agent prompt. In Observability, choose Copy agent prompt at the top right of the Requests table. Paste the prompt into your coding agent and replace the key placeholder with one of your keys. The agent then answers questions such as "why did requests fail today?" or "what did request X send?" with links back to each request. The same prompt is on Setup prompts.

List requests

GET /api/orgs/{org_id}/usage/requests returns newest first unless sorted. All parameters are optional and combine with AND. The same filters work on /sessions, /traces, /requests/search and the export.

ParameterMeaning
window24h (default), 7d or 30d, ending now.
start, endAn exact range instead of window (ISO 8601; start inclusive, end exclusive).
model · provider · api_key_id · end_user · status · failure_class · laneComma-separated values; a row matches any of them. status is completed, failed, incomplete or cancelled; lane is platform or byok.
excludeRepeatable field:value, such as exclude=model:gpt-6-luna, to leave rows out.
session · trace_idOne session id (every request has one: the id your agent sent, else the conversation the gateway recognized, else its trace id), or one 32-character trace id.
pathA step path prefix: /plan/research matches /plan/research/search-1.
tag · tag_score · tag_firedtag=key:value, one per key (key:* for any value; a repeated key answers 400), tag_score=key:min:max, and one trace tag id that fired.
prompt_group · conversation_groupThe 12-character handles a request shows: requests that share a system prompt and tools, or one conversation.
country · regionWhere the request came from: ISO country codes (US, FR) and continents (AF, AN, AS, EU, NA, OC, SA). One location filter: a request matches any listed country or any country of a listed region. exclude=country:XX leaves a country out.
value_plan · value_success · value_own_useThe stored value tag of a captured request: plan tiers (free, pro, max, ultra), whether it succeeded (1 or 0), and whether it is eligible for our own use (1 or 0). A request with no stored capture has no value tag, so any of these leaves it out.
cost_min · cost_maxAll-in cost range in nano-USD (1,000,000,000 is one dollar).
latency_min · latency_max · ttft_min · ttft_maxLatency and time to first token ranges in milliseconds.
tokens_min · tokens_maxInput plus output tokens range.
cache1: only requests with recorded cached input tokens.
sort · dirsort is time (default), cost, latency, ttft or tokens; dir is desc (default) or asc. Every sort combines with every filter.
limit1 to 200 rows per page (default 50); outside that answers 400.

Pagination

The response is {requests, next_cursor, live_cursor, total}. While next_cursor is not null, send the same query again with cursor set to it. The cursor freezes the window when the first page is read, so pages stay in exact order while new requests arrive. A cursor sent with a different query answers 400.

GET /api/orgs/{org_id}/usage/requests
curl "https://api-pr-902980.preview.experientiallabs.ai/api/orgs/$ORG_ID/usage/requests?window=24h&status=failed&sort=cost&limit=50" \
-H "Authorization: Bearer $EXPLABS_API_KEY"

New requests only

To follow the log, keep the newest-first query and send after set to the last live_cursor you received. The answer holds only requests newer than it, oldest first, and a new live_cursor. Never re-read pages you already have.

Fields

FieldMeaning
request_id · created_atThe request id (the x-request-id response header) and when it settled.
model · provider · laneThe model slug, the provider that served it, and whose money it rode. provider and lane are null when nothing was dispatched.
api_key_id · key_labelThe key that made the request (null when that key was deleted).
status · failure_class · error_messageTerminal status and, for a request that did not complete, the sanitized reason.
incomplete_reasonWhy an incomplete request stopped (max_tokens or the engine's reason).
latency_ms · ttft_msTotal latency and time to first token, in milliseconds.
input_tokens · cached_input_tokens · output_tokens · reasoning_tokensToken counts. Cached input is part of input; reasoning is part of output.
real_cost_usd · cost_usd · estimated_cost_usd · free_usd · pricing_knownreal_cost_usd is what the call cost, whoever paid: charged credits (cost_usd) plus the estimate for your own provider key (estimated_cost_usd). A free promotional request carries its list value in free_usd. With pricing_known false, 0 means unpriced, not free.
attempt_countProvider dispatches; 0 means it failed before any dispatch.
tools_usedDistinct tool names the request called (names only).
prompt_group · conversation_groupShort handles: same agent configuration, same conversation.
attribution_labelThe end-user label your request sent, or null.
countryWhere the request came from (ISO country code), or null when the gateway could not locate it.
session_id · trace_id · parent_request_id · pathWhere the request sits in its agent run: its session, its trace, the request it continued, and its step path.
cost_breakdown · zero_cost_reason (one request only)How the cost was built (each priced part: tokens, rate per million, amount; the list price, any discount and whether long-context rates applied), and, for a request that cost nothing, why: cache_hit, byok, promotion, plan_discount, provider_free_tier, refused_before_dispatch, no_usage or unpriced_fallback.
body (one request only)With include_body=true: messages, request (tools and settings), response and wire_request. null when nothing was captured.

Sessions and traces

A session groups the requests that carry one session id (X-Explabs-Session-Id, or a Helicone, LiteLLM or OpenTelemetry session header). GET .../sessions lists them with totals computed from every request, and GET .../sessions/{session_id} returns one with its neighbors. An unknown id answers 404 session_not_found.

For a long session, read /skeleton first: one line per request or span with its parent, start, duration, model, status, tokens and cost, and no bodies, so a 5,000-request session is about 1 MB. Then read one body with /usage/requests/{request_id}/prompt when you need it. Parents come from real links (the previous response id, Claude Code subagent ids, traceparent). A tool span marked inf: 1 was inferred from traffic, and its timing is an estimate. /turns gives each request's new messages only, and /export streams the whole session with bodies.

Search

GET .../requests/search?q= matches the new text of each request (messages, tool results, errors and the response) within one organization and one time range: the last 24 hours by default, at most 30 days. Each hit carries snippets with highlights, start and end offsets into the snippet text. Search within one session or trace with /sessions/{session_id}/search or /traces/{trace_id}/search.

Read one request

GET /api/orgs/{org_id}/usage/requests/{request_id} returns the list row for one request. Add include_body=true to inline its captured prompt and response as body: messages, request (tools, tool choice and sampling settings), response (the JSON body, or the stream's frames) and wire_request (the request as the gateway received it, with secrets removed from headers). body is null when the request was not captured.

The request id is the x-request-id header of the response you received. A request appears here once it settles, shortly after the response ends.

GET /api/orgs/{org_id}/usage/requests/{request_id}
curl "https://api-pr-902980.preview.experientiallabs.ai/api/orgs/$ORG_ID/usage/requests/$REQUEST_ID?include_body=true" \
-H "Authorization: Bearer $EXPLABS_API_KEY"

GET .../usage/requests/{request_id}/attempts lists every provider dispatch of the request in order: provider, lane, state, failure_class, error_message, timestamps and tokens. Read it when a request retried or fell back to another provider.

When prompts and responses are stored

  • Bodies are stored only while your organization's prompt capture is on. Read it with GET /api/orgs/{org_id}/telemetry-settings (capture_prompt_content).
  • Requests routed under zero data retention are never stored, even with capture on.
  • A prompt whose response never arrived is kept for two hours, then removed.
  • Requests served on your own provider key or a connected Claude or ChatGPT plan follow the capture setting like any other request.

Everything else on this page (model, tokens, cost, latency, status, errors) is recorded for every request, whatever the capture setting. See Data controls.

Latency and spend rollups

These read the whole window, not a page of rows. Each takes window (24h, 7d or 30d). timeseries, latency and by-provider also filter by model, api_key_id and lane. A 24h window buckets hourly; 7d and 30d bucket daily. timeseries?compare=true adds the previous period's totals.

For exact grouped reports over any dates, use the Spend API (provisioning key). For a full export of settled requests, use POST /api/v1/usage/exports on the Cost API.

Errors and common mistakes

  • 401: the key is wrong or revoked.
  • 404 on every route: the org_id in the path is not your key's organization. Use the one from /api/whoami.
  • 404 on one request: it belongs to another organization, or it has not settled yet. Retry after a few seconds.
  • 400: an unknown parameter or value (status, window, lane, sort, dir), a repeated tag key, a start after end, or a cursor sent with a different query. Errors are {error, code}; the error names the parameter. An unknown status is refused rather than returning an empty list.
  • 422: a query too broad to read in time (query_too_broad); narrow the window or add a filter.
  • 429: your organization's keys sent too many reads at once, or the rollups are busy. Wait the Retry-After seconds and retry. For more than a few pages of requests, use the streamed export instead of paging the log.
  • body is null: capture is off, the request was routed under zero data retention, or its prompt expired before a response arrived.
PreviousCost APINextTraces and sessions