Skip to main content

Documentation Index

Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Traces API — ingest and query LLM traces

Ingest LLM traces via the batch collector or direct CRUD endpoints, add spans, and query traces by status or name for analysis and evals.
Traces give Evalgate visibility into your LLM calls in production. Each trace represents a single request-response unit (or multi-step workflow), and each span inside it captures a discrete operation — an LLM call, a retrieval step, or a tool invocation. Use the collector endpoint for high-volume production ingestion, and the direct trace and span endpoints for lower-volume or programmatic workflows.

​
POST /api/collector — batch ingest (recommended)

The collector endpoint accepts a batch of traces in a single authenticated request. It applies sampling rules before writing — 10% of successful traces are sampled, while 100% of error traces are always captured. This is the recommended path for mirroring production traffic into Evalgate. 
curl https://evalgate.com/api/collector \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "name": "Chat Completion",
        "traceId": "trace-1706000000-abc123",
        "organizationId": 1,
        "status": "success",
        "durationMs": 1450,
        "metadata": { "model": "gpt-4o", "userId": "user-42" }
      }
    ]
  }'
The collector processes the batch transactionally. All traces in a batch either succeed or fail together.

​
GET /api/traces — list 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"

​
Query parameters

​
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 (LIKE search).

​
Response

{
  "traces": [
    {
      "id": 42,
      "name": "Chat Completion",
      "traceId": "trace-1706000000-abc123",
      "organizationId": 1,
      "status": "success",
      "durationMs": 1450,
      "metadata": { "model": "gpt-4o" },
      "createdAt": "2026-03-15T10:30:00.000Z"
    }
  ]
}

​
POST /api/traces — create a trace

Creates a single trace record directly. 
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",
    "organizationId": 123,
    "status": "pending",
    "durationMs": 1500,
    "metadata": { "source": "api-server" }
  }'

​
Request body

​
name
string
required
Display name for this trace.
​
traceId
string
required
Unique identifier string you assign. Use a stable, reproducible ID so you can correlate traces with your own request logs.
​
organizationId
integer
required
Numeric ID of the organization that owns this trace.
​
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. Use this to store model name, user ID, session ID, or any context useful for filtering in the dashboard.

​
Response (201)

{
  "id": 42,
  "name": "Workflow: Customer Support Flow",
  "traceId": "workflow-1706000000-abc123def",
  "organizationId": 123,
  "status": "pending",
  "durationMs": null,
  "metadata": { "source": "api-server" },
  "createdAt": "2026-02-06T04:00:00.000Z"
}

​
GET /api/traces/ — get trace details

Returns a single trace along with all of its spans. 
curl https://evalgate.com/api/traces/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path parameters

​
id
integer
required
Numeric ID of the trace to retrieve.

​
Response

{
  "trace": {
    "id": 42,
    "name": "Workflow: Customer Support Flow",
    "traceId": "workflow-1706000000-abc123def",
    "status": "success",
    "durationMs": 1450,
    "createdAt": "2026-02-06T04:00:00.000Z"
  },
  "spans": [
    {
      "id": 101,
      "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 }
    }
  ]
}
​
trace
object
The trace record.
​
spans
array
All spans attached to this trace, ordered by startTime.

​
POST /api/traces//spans — add a span

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

​
Path parameters

​
id
integer
required
Numeric ID of the parent trace.

​
Request body

​
name
string
required
Display name for this span.
​
spanId
string
required
Unique identifier string you assign to this span.
​
type
string
required
Span type: llm, tool, or retrieval.
​
startTime
string
required
ISO 8601 timestamp when the span started.
​
input
string
The input to this operation (prompt, query, tool arguments, etc.).
​
output
string
The output from this operation (completion, result, retrieved text, etc.).
​
metadata
object
Arbitrary JSON for additional context such as token counts, latency, or model name.