Search Traces With Advanced Filters

Trace storage

Configure AgentOS tracing with a registered trace-capable database and an exporter that writes to it. An ordinary model run alone does not guarantee stored traces. Select db_id when multiple databases are registered. These trace endpoints select storage by db_id only; they do not accept a table selector.

Trace ownership follows the effective user scope: JWT user isolation is opt-in, while non-admin service-account PAT callers self-scope. Configured authorization also requires trace read access. Use IDs returned by trace listing for detail requests.

Send an advanced filter

Use a JSON request body. For example, find successful traces:

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

group_by="run" returns individual trace details, not an aggregate for each run ID. group_by="session" returns session trace summaries. Both use data and meta. Pages start at 1; limit is from 1 through 100.

Use field names from Get Trace Filter Schema. CONTAINS and STARTSWITH match case-insensitively and escape SQL wildcards. IN uses a values array; NOT wraps one condition. AND and OR wrap a conditions array.

Invalid operators return 400. On current SQLite, a syntactically valid filter naming an unknown column can instead return 200 with empty data because the database error is caught. An empty result does not prove the filter's field name is valid.

POST/traces/search

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}

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

db_id?|

Database ID to query traces from

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

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 }

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/traces/search' \  --header 'Content-Type: application/json' \  --data-raw '{}'
{  "data": [    {      "trace_id": "string",      "name": "string",      "status": "string",      "duration": "string",      "start_time": "2019-08-24T14:15:22Z",      "end_time": "2019-08-24T14:15:22Z",      "total_spans": 0,      "error_count": 0,      "input": "string",      "output": "string",      "error": "string",      "run_id": "string",      "session_id": "string",      "user_id": "string",      "agent_id": "string",      "team_id": "string",      "workflow_id": "string",      "created_at": "2019-08-24T14:15:22Z",      "tree": [        {          "id": "string",          "name": "string",          "type": "string",          "duration": "string",          "start_time": "2019-08-24T14:15:22Z",          "end_time": "2019-08-24T14:15:22Z",          "status": "string",          "input": "string",          "output": "string",          "error": "string",          "spans": [            {}          ],          "step_type": "string",          "metadata": {},          "extra_data": {}        }      ]    }  ],  "meta": {    "page": 0,    "limit": 20,    "total_pages": 0,    "total_count": 0,    "search_time_ms": 0  }}