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,
  "spans_written": 1,
  "spans_existing": 0,
  "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%.

span_id is unique within its trace, matching the OpenTelemetry identity model. Replaying the same (trace_id, span_id) is idempotent and increments spans_existing; the same span_id on a different trace is persisted as distinct evidence. A request containing a duplicate span_id within one trace is rejected before persistence.

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",
      "span_count": 1,
      "spans_written": 1,
      "spans_existing": 0
    }
  ],
  "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"

integer

Maximum number of traces to return. Defaults to 50, maximum 100.

integer

Number of results to skip for pagination. Defaults to 0.

string

Filter by trace status: pending, success, or error.

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" }
  }'

string

required

Display name for this trace.

string

Unique identifier string you assign. If omitted, EvalGate generates one.

string

Initial status: pending, success, or error. Defaults to pending.

integer

End-to-end duration of the traced operation in milliseconds.

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"

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 }
  }'

integer

required

Numeric database ID of the parent trace.

string

required

Display name for this span.

string

Unique identifier string you assign to this span. If omitted, EvalGate generates one.

string

Span type, such as llm, tool, or retrieval.

any

The input to this operation.

any

The output from this operation.

object

Additional context such as token counts, latency, model name, or tool name.

Overview

Endpoints

Traces API

Traces API

POST /api/collector

Response

POST /api/collector/batch

Response

GET /api/traces

POST /api/traces

GET /api/traces/

POST /api/traces//spans

​Traces API

​POST /api/collector

​Response

​POST /api/collector/batch

​Response

​GET /api/traces

​POST /api/traces

​GET /api/traces/

​POST /api/traces//spans

Traces API

POST /api/collector

Response

POST /api/collector/batch

Response

GET /api/traces

POST /api/traces

GET /api/traces/

POST /api/traces//spans