Search Traces with Advanced Filters

curl --request POST \
  --url https://api.example.com/traces/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "group_by": "run",
  "page": 1,
  "limit": 20
}
'

{
  "data": [
    {
      "trace_id": "<string>",
      "name": "<string>",
      "status": "<string>",
      "duration": "<string>",
      "start_time": "2023-11-07T05:31:56Z",
      "end_time": "2023-11-07T05:31:56Z",
      "total_spans": 123,
      "error_count": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "tree": [
        {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "duration": "<string>",
          "start_time": "2023-11-07T05:31:56Z",
          "end_time": "2023-11-07T05:31:56Z",
          "status": "<string>",
          "input": "<string>",
          "output": "<string>",
          "error": "<string>",
          "spans": [
            "<unknown>"
          ],
          "step_type": "<string>",
          "metadata": {},
          "extra_data": {}
        }
      ],
      "input": "<string>",
      "output": "<string>",
      "error": "<string>",
      "run_id": "<string>",
      "session_id": "<string>",
      "user_id": "<string>",
      "agent_id": "<string>",
      "team_id": "<string>",
      "workflow_id": "<string>"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "total_pages": 0,
    "total_count": 0,
    "search_time_ms": 0
  }
}

Traces

Search Traces with Advanced Filters

Search traces using the FilterExpr DSL for complex, composable queries.

Group By Mode:

run (default): Returns PaginatedResponse[TraceDetail] with full span trees
session: Returns PaginatedResponse[TraceSessionStats] with aggregated session stats

Supported Operators:

Comparison: EQ, NEQ, GT, GTE, LT, LTE
Inclusion: IN
String matching: CONTAINS (case-insensitive substring), STARTSWITH (prefix)
Logical: AND, OR, NOT

Filterable Fields: trace_id, name, status, start_time, end_time, duration_ms, run_id, session_id, user_id, agent_id, team_id, workflow_id, created_at

Example Request Body (runs):

{
  "filter": {"op": "EQ", "key": "status", "value": "OK"},
  "group_by": "run",
  "page": 1,
  "limit": 20
}

Example Request Body (sessions):

{
  "filter": {"op": "CONTAINS", "key": "agent_id", "value": "stock"},
  "group_by": "session",
  "page": 1,
  "limit": 20
}

POST

traces

Search Traces with Advanced Filters

curl --request POST \
  --url https://api.example.com/traces/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {},
  "group_by": "run",
  "page": 1,
  "limit": 20
}
'

{
  "data": [
    {
      "trace_id": "<string>",
      "name": "<string>",
      "status": "<string>",
      "duration": "<string>",
      "start_time": "2023-11-07T05:31:56Z",
      "end_time": "2023-11-07T05:31:56Z",
      "total_spans": 123,
      "error_count": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "tree": [
        {
          "id": "<string>",
          "name": "<string>",
          "type": "<string>",
          "duration": "<string>",
          "start_time": "2023-11-07T05:31:56Z",
          "end_time": "2023-11-07T05:31:56Z",
          "status": "<string>",
          "input": "<string>",
          "output": "<string>",
          "error": "<string>",
          "spans": [
            "<unknown>"
          ],
          "step_type": "<string>",
          "metadata": {},
          "extra_data": {}
        }
      ],
      "input": "<string>",
      "output": "<string>",
      "error": "<string>",
      "run_id": "<string>",
      "session_id": "<string>",
      "user_id": "<string>",
      "agent_id": "<string>",
      "team_id": "<string>",
      "workflow_id": "<string>"
    }
  ],
  "meta": {
    "page": 0,
    "limit": 20,
    "total_pages": 0,
    "total_count": 0,
    "search_time_ms": 0
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

db_id

string | null

Database ID to query traces from

Body

application/json

Request body for POST /traces/search with advanced filtering.

The filter field accepts a FilterExpr DSL dict supporting composable queries with AND/OR/NOT logic and operators like EQ, NEQ, GT, GTE, LT, LTE, IN, CONTAINS, STARTSWITH.

Example for run grouping (default): { "filter": { "op": "AND", "conditions": [ {"op": "EQ", "key": "status", "value": "OK"}, {"op": "CONTAINS", "key": "user_id", "value": "admin"} ] }, "group_by": "run", "page": 1, "limit": 20 }

Example for session grouping: { "filter": {"op": "EQ", "key": "agent_id", "value": "my-agent"}, "group_by": "session", "page": 1, "limit": 20 }

filter

Filter · object

FilterExpr DSL as JSON dict. Supports operators: EQ, NEQ, GT, GTE, LT, LTE, IN, CONTAINS, STARTSWITH, AND, OR, NOT.

group_by

enum<string>

default:run

Grouping mode: 'run' returns individual TraceDetail, 'session' returns aggregated TraceSessionStats.

Available options:

run,

session

page

integer

default:1

Page number (1-indexed)

Required range: x >= 1

limit

integer

default:20

Number of traces per page (max 100)

Required range: 1 <= x <= 100

Response

Successful Response

PaginatedResponse[TraceDetail]
PaginatedResponse[TraceSessionStats]

data

TraceDetail · object[]

required

List of items for the current page

Show child attributes