Skip to main content

​
Traces API

Traces give EvalGate visibility into LLM calls and multi-step AI workflows. Each trace belongs to the organization associated with your API key. Each span captures one operation inside the trace, such as an LLM call, retrieval step, tool call, or agent step.

​
POST /api/collector

Use the collector when you want to ingest one trace and all of its spans in a single request. The trace and spans are inserted transactionally. 
curl https://evalgate.com/api/collector \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trace_id": "trace-1706000000-abc123",
    "name": "Chat Completion",
    "status": "success",
    "duration_ms": 1450,
    "source": "sdk",
    "environment": "production",
    "metadata": { "model": "gpt-4o", "userId": "user-42" },
    "spans": [
      {
        "span_id": "span-1706000001",
        "type": "llm",
        "name": "OpenAI API Call",
        "input": "What is your refund policy?",
        "output": "Our refund policy allows returns within 30 days.",
        "model": "gpt-4o",
        "vendor": "openai",
        "metrics": {
          "prompt_tokens": 42,
          "completion_tokens": 28,
          "total_time_ms": 1200
        }
      }
    ]
  }'

​
Response

{
  "trace_id": "trace-1706000000-abc123",
  "trace_db_id": 42,
  "span_count": 1,
  "feedback_recorded": false,
  "queued_for_analysis": false,
  "sampling_reason": "skipped"
}
Sampling controls whether an ingested trace is queued for failure analysis. Errors and thumbs-down feedback are always analyzed. Successful traces are sampled for analysis at the server default rate of 10%.

​
POST /api/collector/batch

Use the batch collector for up to 100 traces per request. Each trace is ingested independently, so one failed trace does not fail the whole batch. 
curl https://evalgate.com/api/collector/batch \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "trace_id": "trace-1706000000-abc123",
        "name": "Chat Completion",
        "status": "success",
        "spans": [
          {
            "span_id": "span-1",
            "type": "llm",
            "name": "LLM Call",
            "input": "Hello",
            "output": "Hi there"
          }
        ]
      }
    ]
  }'

​
Response

{
  "results": [
    {
      "trace_id": "trace-1706000000-abc123",
      "status": "accepted"
    }
  ],
  "accepted": 1,
  "failed": 0
}

​
GET /api/traces

Returns traces for the authenticated organization. Supports filtering and pagination. 
curl "https://evalgate.com/api/traces?limit=20&status=error" \
  -H "Authorization: Bearer YOUR_API_KEY"
​
limit
integer
Maximum number of traces to return. Defaults to 50, maximum 100.
​
offset
integer
Number of results to skip for pagination. Defaults to 0.
​
status
string
Filter by trace status: pending, success, or error.
​
search
string
Filter by trace name using a partial match.

​
POST /api/traces

Creates a single trace record directly. Use this for low-volume programmatic workflows. Use /api/collector when you want to create the trace and spans together. 
curl https://evalgate.com/api/traces \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Workflow: Customer Support Flow",
    "traceId": "workflow-1706000000-abc123def",
    "status": "pending",
    "durationMs": 1500,
    "metadata": { "source": "api-server" }
  }'
​
name
string
required
Display name for this trace.
​
traceId
string
Unique identifier string you assign. If omitted, EvalGate generates one.
​
status
string
Initial status: pending, success, or error. Defaults to pending.
​
durationMs
integer
End-to-end duration of the traced operation in milliseconds.
​
metadata
object
Arbitrary JSON object for model name, user ID, session ID, feature flags, or other context.

​
GET /api/traces/

Returns a single trace and its spans. 
curl https://evalgate.com/api/traces/42 \
  -H "Authorization: Bearer YOUR_API_KEY"
​
id
integer
required
Numeric database ID of the trace to retrieve.

​
POST /api/traces//spans

Adds a span to an existing trace. 
curl https://evalgate.com/api/traces/42/spans \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI API Call",
    "spanId": "span-1706000001",
    "type": "llm",
    "startTime": "2026-02-06T04:00:00.100Z",
    "input": "What is your refund policy?",
    "output": "Our refund policy allows returns within 30 days.",
    "metadata": { "model": "gpt-4o", "tokens": 150 }
  }'
​
id
integer
required
Numeric database ID of the parent trace.
​
name
string
required
Display name for this span.
​
spanId
string
Unique identifier string you assign to this span. If omitted, EvalGate generates one.
​
type
string
Span type, such as llm, tool, or retrieval.
​
input
any
The input to this operation.
​
output
any
The output from this operation.
​
metadata
object
Additional context such as token counts, latency, model name, or tool name.