API ReferenceTraces & Spans

Traces API

Ingest traces from your AI agents and query historical data.

Ingest Traces (OTLP)

ThinkHive supports OpenTelemetry Protocol (OTLP) for trace ingestion.

POST /v1/traces

Headers:

Content-Type: application/json
Authorization: Bearer thk_your_api_key

Request Body (OTLP Format):

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          { "key": "service.name", "value": { "stringValue": "my-agent" } }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "abc123...",
              "spanId": "def456...",
              "name": "llm-call",
              "kind": 1,
              "startTimeUnixNano": "1704067200000000000",
              "endTimeUnixNano": "1704067201000000000",
              "attributes": [
                { "key": "llm.model", "value": { "stringValue": "gpt-4" } },
                { "key": "llm.input_tokens", "value": { "intValue": "150" } }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Ingest Traces (Simple Format)

POST /api/traces

Request Body:

{
  "agentId": "agent_abc123",
  "spans": [
    {
      "name": "customer-chat",
      "type": "llm",
      "startTime": "2024-01-15T10:00:00Z",
      "endTime": "2024-01-15T10:00:02Z",
      "input": "How do I reset my password?",
      "output": "To reset your password, go to Settings...",
      "model": "gpt-4",
      "tokens": {
        "input": 25,
        "output": 150,
        "total": 175
      },
      "metadata": {
        "customerId": "cust_123",
        "channel": "chat"
      }
    }
  ],
  "outcome": "success"
}

Response:

{
  "success": true,
  "data": {
    "traceId": "tr_xyz789",
    "spanCount": 1,
    "ingested": true
  }
}

List Traces

GET /api/traces

Query Parameters:

ParameterTypeDescription
agentIdstringFilter by agent
outcomestringFilter by outcome (success, failure)
startDatestringStart date (ISO 8601)
endDatestringEnd date (ISO 8601)
pagenumberPage number
limitnumberItems per page (max 100)

Example:

GET /api/traces?agentId=agent_abc123&outcome=failure&limit=20

Response:

{
  "success": true,
  "data": [
    {
      "id": "tr_xyz789",
      "agentId": "agent_abc123",
      "outcome": "failure",
      "userMessage": "How do I...",
      "agentResponse": "I apologize...",
      "latencyMs": 1500,
      "tokenCount": 200,
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}

Get Trace

GET /api/traces/:id

Response:

{
  "success": true,
  "data": {
    "id": "tr_xyz789",
    "agentId": "agent_abc123",
    "outcome": "failure",
    "spans": [
      {
        "id": "span_1",
        "name": "retrieval",
        "type": "retrieval",
        "query": "password reset",
        "documents": [
          { "id": "doc_1", "content": "...", "score": 0.85 }
        ],
        "latencyMs": 200
      },
      {
        "id": "span_2",
        "name": "llm-response",
        "type": "llm",
        "input": "Context: ... Question: How do I...",
        "output": "To reset your password...",
        "model": "gpt-4",
        "tokens": { "input": 150, "output": 100 },
        "latencyMs": 1200
      }
    ],
    "metadata": {
      "customerId": "cust_123",
      "sessionId": "sess_abc"
    },
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

Get Trace Spans

GET /api/traces/:id/spans

Response:

{
  "success": true,
  "data": [
    {
      "id": "span_1",
      "traceId": "tr_xyz789",
      "parentSpanId": null,
      "name": "rag-pipeline",
      "type": "chain",
      "startTime": "2024-01-15T10:00:00Z",
      "endTime": "2024-01-15T10:00:02Z",
      "children": ["span_2", "span_3"]
    },
    {
      "id": "span_2",
      "traceId": "tr_xyz789",
      "parentSpanId": "span_1",
      "name": "retrieval",
      "type": "retrieval",
      ...
    }
  ]
}

Delete Trace

DELETE /api/traces/:id

Response:

{
  "success": true,
  "message": "Trace deleted successfully"
}

Trace Statistics

GET /api/traces/stats

Query Parameters:

ParameterTypeDescription
agentIdstringAgent ID
periodstringTime period (24h, 7d, 30d)

Response:

{
  "success": true,
  "data": {
    "totalTraces": 15000,
    "successRate": 0.85,
    "failureRate": 0.15,
    "avgLatencyMs": 1200,
    "p50LatencyMs": 1000,
    "p95LatencyMs": 2500,
    "p99LatencyMs": 4000,
    "tokenUsage": {
      "total": 2500000,
      "avgPerTrace": 166
    },
    "byOutcome": {
      "success": 12750,
      "failure": 2250
    }
  }
}

Supported Trace Formats

ThinkHive can ingest traces from multiple formats:

Native ThinkHive format (shown above)

Auto-Detection: ThinkHive automatically detects the trace format when using the /api/explainer/analyze endpoint.

Trace Sessions

Manage trace sessions to group related traces.

GET /api/sessions
POST /api/sessions
PATCH /api/sessions/:id

Trace Evaluation Link

Connect traces to evaluation runs for quality tracking.

GET /api/trace-evaluation?traceId=tr_xyz789
POST /api/trace-evaluation

Next Steps

AgentsIssues & Fixes