Skip to content
SideSeat

Traces API

List Traces

Section titled “List Traces”
GET /api/v1/project/{project_id}/otel/traces

Query traces with pagination and filters.

Query Parameters

Section titled “Query Parameters”

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number (default: 1) | | limit | number | Items per page (default: 50) | | order_by | string | Sort field (e.g., start_time:desc) | | session_id | string | Filter by session ID | | user_id | string | Filter by user ID | | environment | string or array | Filter by environment | | from_timestamp | string | Filter from timestamp (ISO 8601) | | to_timestamp | string | Filter to timestamp (ISO 8601) | | filters | JSON | Advanced filters (see below) | | include_nongenai | boolean | Include non‑GenAI traces (default: false) |

Response

Section titled “Response”
{
  "data": [
    {
      "trace_id": "abc123def456",
      "trace_name": "agent.run",
      "start_time": "2025-01-26T10:12:34Z",
      "end_time": "2025-01-26T10:12:36Z",
      "duration_ms": 1890,
      "session_id": "session-789",
      "user_id": "user-123",
      "environment": "development",
      "span_count": 5,
      "total_tokens": 350,
      "total_cost": 0.018
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total_items": 127,
    "total_pages": 3
  }
}

Examples

Section titled “Examples”
Terminal window
# List recent traces
curl "http://localhost:5388/api/v1/project/default/otel/traces?page=1&limit=20"


# Filter by session
curl "http://localhost:5388/api/v1/project/default/otel/traces?session_id=session-789"


# Filter by environment
curl "http://localhost:5388/api/v1/project/default/otel/traces?environment=development"

Get Trace

Section titled “Get Trace”
GET /api/v1/project/{project_id}/otel/traces/{trace_id}

Get a single trace with nested spans.

Optional query params:

  • include_raw_span=true to include the raw OTLP span JSON

Get Trace Messages

Section titled “Get Trace Messages”
GET /api/v1/project/{project_id}/otel/traces/{trace_id}/messages

Get normalized messages (SideML format) for a trace.

Delete Traces

Section titled “Delete Traces”
DELETE /api/v1/project/{project_id}/otel/traces

Delete traces in a batch. There is no per-trace DELETE /traces/{trace_id} route - that path is registered for GET only and answers DELETE with 405. Pass the ids in the body:

{"trace_ids": ["4bf92f3577b34da6a3ce929d0e0e4736"]}

Get Filter Options

Section titled “Get Filter Options”
GET /api/v1/project/{project_id}/otel/traces/filter-options

Get available filter values for building UI dropdowns.

Advanced Filters

Section titled “Advanced Filters”

Pass a JSON array in the filters query param. Each entry is tagged by type and carries a column, an operator, and (except for null) a value. Operators are SQL-shaped literals, not names - "=", not "eq".

[{"type": "string", "column": "environment", "operator": "=", "value": "production"}]

Types and operators

Section titled “Types and operators”

| type | Operators | Value | |--------|-----------|-------| | string | =, contains, starts_with, ends_with | string | | number | =, >, <, >=, <= | number | | datetime | >, <, >=, <= | RFC 3339 string | | string_options | any of, none of | array of strings | | boolean | =, <> | boolean | | null | is null, is not null | omitted |

Each endpoint allows its own set of columns and rejects the rest with INVALID_FILTER_COLUMN. The timestamp column differs by endpoint: /traces and /sessions use start_time / end_time, while /spans also accepts timestamp_start / timestamp_end.

Terminal window
curl -G "http://localhost:5388/api/v1/project/default/otel/traces" \
  --data-urlencode 'filters=[{"type":"number","column":"duration_ms","operator":">","value":1000}]'

Next Steps

Section titled “Next Steps”