Skip to main content
Base URL: https://api.zeroeval.com All requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_ZEROEVAL_API_KEY
Get an API key from Settings → API Keys.

​
Spans

​
Ingest Spans

POST /spans
Send one or more spans. Traces and sessions referenced by the spans are auto-created if they don’t exist. Request body: SpanCreate[]
FieldTypeRequiredDefaultDescription
trace_idstring (UUID)Yes—Trace this span belongs to
namestringYes—Descriptive name
started_atISO 8601Yes—When the span started
idstring (UUID)Noauto-generatedClient-provided span ID
kindstringNo"generic"generic, llm, tts, http, database, vector_store
statusstringNonullunset, ok, error
ended_atISO 8601NonullWhen the span completed
duration_msfloatNonullDuration in milliseconds
costfloatNoauto-calculatedCost (auto-calculated for LLM spans)
parent_span_idstring (UUID)NonullParent span for nesting
session_idstring (UUID)NonullSession to associate with
sessionobjectNonull{"id": "...", "name": "..."} — alternative to session_id
input_datastringNonullInput data (JSON string for messages)
output_datastringNonullOutput/response text
attributesobjectNo{}Arbitrary key-value attributes
tagsobjectNo{}Key-value tags for filtering
trace_tagsobjectNo{}Tags applied to the parent trace
session_tagsobjectNo{}Tags applied to the parent session
error_codestringNonullError code or exception class
error_messagestringNonullError description
error_stackstringNonullStack trace
code_filepathstringNonullSource file path
code_linenointNonullSource line number
curl -X POST https://api.zeroeval.com/spans \
  -H "Authorization: Bearer $ZEROEVAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "trace_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "chat_completion",
    "kind": "llm",
    "started_at": "2025-01-15T10:30:00Z",
    "ended_at": "2025-01-15T10:30:02Z",
    "status": "ok",
    "attributes": {
      "provider": "openai",
      "model": "gpt-4o",
      "inputTokens": 150,
      "outputTokens": 230
    },
    "input_data": "[{\"role\": \"user\", \"content\": \"What is the capital of France?\"}]",
    "output_data": "The capital of France is Paris.",
    "tags": {"environment": "production"}
  }]'
Response: SpanRead[] (200)

​
LLM Cost Calculation

For automatic cost calculation on LLM spans, set kind to "llm" and include these attributes:
AttributeRequiredDescription
providerYes"openai", "gemini", "anthropic"
modelYes"gpt-4o", "claude-3-5-sonnet", etc.
inputTokensYesNumber of input tokens
outputTokensYesNumber of output tokens
Cost is calculated as: (inputTokens × inputPrice + outputTokens × outputPrice) / 1,000,000

​
Query Spans

GET /spans
Retrieve spans with filtering, sorting, and pagination.
ParameterTypeDefaultDescription
idstring—Filter by span ID
trace_idstring—Filter by trace ID
parent_span_idstring—Filter by parent; "null" for root spans
span_kindstring—llm, generic, tts, http, etc.
created_beforeISO 8601—Upper bound on created_at
created_afterISO 8601—Lower bound on created_at
namesstring—Comma-separated span names
error_codesstring—Comma-separated error codes
has_errorbool—true or false
duration_minfloat—Minimum duration (ms)
duration_maxfloat—Maximum duration (ms)
cost_minfloat—Minimum cost
cost_maxfloat—Maximum cost
sort_bystring—started_at, name, status, duration_ms, cost, kind
sort_orderstringdescasc or desc
limitint50001–10000
offsetint0Pagination offset
Any unrecognized query parameter is treated as a tag filter (e.g. ?environment=production). Response: SpanRead[] (200)

​
Get Span Attachments

GET /spans/{span_id}/attachments
Returns all attachments (images, screenshots) for a span with presigned URLs. Response: 
{
  "attachments": [
    {
      "type": "image",
      "url": "https://...",
      "label": "Homepage screenshot"
    }
  ],
  "count": 1
}

​
Traces

​
Create Traces

POST /traces
Create one or more traces. Traces are also auto-created when ingesting spans. Request body: TraceCreate[]
FieldTypeRequiredDefaultDescription
session_idstring (UUID)Yes—Parent session
namestringYes—Trace name
started_atISO 8601Yes—Start time
idstring (UUID)Noauto-generatedClient-provided trace ID
statusstringNonullunset, ok, error
ended_atISO 8601NonullEnd time
duration_msfloatNonullDuration in milliseconds
costfloatNonullTotal cost
attributesobjectNo{}Arbitrary attributes
tagsobjectNo{}Key-value tags
Response: TraceRead[] (200)

​
Query Traces

GET /traces
ParameterTypeDefaultDescription
idstring—Filter by trace ID
session_idstring—Filter by session ID
statusstring—Filter by status
created_beforeISO 8601—Upper bound on created_at
created_afterISO 8601—Lower bound on created_at
namesstring—Comma-separated trace names
has_errorbool—true or false
duration_minfloat—Minimum duration (ms)
duration_maxfloat—Maximum duration (ms)
cost_minfloat—Minimum cost
cost_maxfloat—Maximum cost
sort_bystring—started_at, name, status, span_count, duration_ms, cost
sort_orderstringdescasc or desc
limitint501–500
offsetint0Pagination offset
Tag filters work the same as for spans. Response: TraceRead[] (200) Each trace includes:
FieldTypeDescription
idstringTrace ID
session_idstringParent session
namestringTrace name
statusstringunset, ok, error
started_atISO 8601Start time
ended_atISO 8601End time
duration_msfloatDuration
costfloatTotal cost
span_countintNumber of spans
root_span_inputstringInput from the root span
root_span_outputstringOutput from the root span
tagsobjectTags

​
Sessions

​
Create Sessions

POST /sessions
Create one or more sessions. Sessions are also auto-created when ingesting spans with a session_id or session field. Request body: SessionCreate[]
FieldTypeRequiredDefaultDescription
project_idstringYes—Project ID
namestringNonullHuman-readable session name
idstring (UUID)Noauto-generatedClient-provided session ID
attributesobjectNo{}Arbitrary attributes
tagsobjectNo{}Key-value tags
Response: SessionRead[] (200)

​
Query Sessions

GET /sessions
ParameterTypeDefaultDescription
idstring—Filter by session ID
created_beforeISO 8601—Upper bound on created_at
created_afterISO 8601—Lower bound on created_at
namesstring—Comma-separated session names
has_errorbool—true or false
duration_minfloat—Minimum duration
duration_maxfloat—Maximum duration
cost_minfloat—Minimum cost
cost_maxfloat—Maximum cost
sort_bystring—created_at, name, trace_count, cost, duration
sort_orderstringdescasc or desc
limitint501–500
offsetint0Pagination offset
Tag filters work the same as for spans. Response: SessionRead[] (200) Each session includes:
FieldTypeDescription
idstringSession ID
project_idstringProject ID
namestringSession name
trace_countintNumber of traces
error_countintNumber of errors
costfloatTotal cost
durationfloatTotal duration
tagsobjectTags

​
Feedback

To retrieve feedback (human reviews and judge evaluations) for spans, traces, or sessions, use the Feedback API.

​
OpenTelemetry (OTLP)

​
Ingest OTLP Traces

POST /v1/traces
Accepts standard OpenTelemetry Protocol (OTLP) trace data in JSON or protobuf format. Headers:
HeaderValue
AuthorizationBearer YOUR_ZEROEVAL_API_KEY
Content-Typeapplication/json or application/x-protobuf
This endpoint is compatible with the OpenTelemetry Collector’s otlphttp exporter. See OpenTelemetry for collector configuration.