> ## 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 traces with spans, query traces, and understand when traces are analyzed for regression coverage.

# 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.

Collector request bodies use **snake\_case** wire fields (`trace_id`, `span_id`,
`duration_ms`). Do not apply that casing rule to `POST /api/traces`, which
accepts **camelCase** fields such as `traceId` and `durationMs`.

```bash theme={null} theme={null}
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-5.5", "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-5.5",
        "vendor": "openai",
        "metrics": {
          "prompt_tokens": 42,
          "completion_tokens": 28,
          "total_time_ms": 1200
        }
      }
    ]
  }'
```

### Response

```json theme={null} theme={null}
{
  "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"
}
```

> [!NOTE]
>
> 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.

```bash theme={null} theme={null}
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

```json theme={null} theme={null}
{
  "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.

```bash theme={null} theme={null}
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 1000.

**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.

```bash theme={null} theme={null}
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/{id}

Returns a single trace and its spans.

```bash theme={null} theme={null}
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/{id}/spans

Adds a span to an existing trace.

```bash theme={null} theme={null}
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-5.5", "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.