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

```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-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

```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%.
</Note>

`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"
```

<ParamField query="limit" type="integer">
  Maximum number of traces to return. Defaults to 50, maximum 100.
</ParamField>

<ParamField query="offset" type="integer">
  Number of results to skip for pagination. Defaults to 0.
</ParamField>

<ParamField query="status" type="string">
  Filter by trace status: `pending`, `success`, or `error`.
</ParamField>

<ParamField query="search" type="string">
  Filter by trace name using a partial match.
</ParamField>

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

<ParamField body="name" type="string" required>
  Display name for this trace.
</ParamField>

<ParamField body="traceId" type="string">
  Unique identifier string you assign. If omitted, EvalGate generates one.
</ParamField>

<ParamField body="status" type="string">
  Initial status: `pending`, `success`, or `error`. Defaults to `pending`.
</ParamField>

<ParamField body="durationMs" type="integer">
  End-to-end duration of the traced operation in milliseconds.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary JSON object for model name, user ID, session ID, feature flags, or other context.
</ParamField>

## 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"
```

<ParamField path="id" type="integer" required>
  Numeric database ID of the trace to retrieve.
</ParamField>

## 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-4o", "tokens": 150 }
  }'
```

<ParamField path="id" type="integer" required>
  Numeric database ID of the parent trace.
</ParamField>

<ParamField body="name" type="string" required>
  Display name for this span.
</ParamField>

<ParamField body="spanId" type="string">
  Unique identifier string you assign to this span. If omitted, EvalGate generates one.
</ParamField>

<ParamField body="type" type="string">
  Span type, such as `llm`, `tool`, or `retrieval`.
</ParamField>

<ParamField body="input" type="any">
  The input to this operation.
</ParamField>

<ParamField body="output" type="any">
  The output from this operation.
</ParamField>

<ParamField body="metadata" type="object">
  Additional context such as token counts, latency, model name, or tool name.
</ParamField>