Get Trace Statistics By Session

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.

The response contains data (session summaries) and pagination meta. Each summary has session_id, total_traces, first_trace_at and last_trace_at, with optional user/component identity. These are summaries of stored traces, not the complete session conversation or a list of run outputs.

GET/trace_session_stats

Retrieve aggregated trace statistics grouped by session ID with pagination.

Provides insights into:

  • Total traces per session
  • First and last trace timestamps per session
  • Associated user and agent information

Filtering Options:

  • By user ID
  • By agent ID

Use Cases:

  • Monitor session-level activity
  • Track conversation flows
  • Identify high-activity sessions
  • Analyze user engagement patterns

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

user_id?|

Filter by user ID

agent_id?|

Filter by agent ID

team_id?|

Filter by team ID

workflow_id?|

Filter by workflow ID

start_time?|

Filter sessions with traces created after this time (ISO 8601 format with timezone, e.g., '2025-11-19T10:00:00Z' or '2025-11-19T15:30:00+05:30'). Times are converted to UTC for comparison.

end_time?|

Filter sessions with traces created before this time (ISO 8601 format with timezone, e.g., '2025-11-19T11:00:00Z' or '2025-11-19T16:30:00+05:30'). Times are converted to UTC for comparison.

page?Page

Page number (1-indexed)

Range1 <= value
Default1
limit?Limit

Number of sessions per page

Range1 <= value
Default20
db_id?|

Database ID to query statistics from

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/trace_session_stats'
{  "data": [    {      "session_id": "37029bc6-1794-4ba8-a629-1efedc53dcad",      "user_id": "kaustubh@agno.com",      "agent_id": "hackernews-agent",      "total_traces": 5,      "first_trace_at": "2025-11-19T10:15:16+00:00",      "last_trace_at": "2025-11-19T10:21:30+00:00"    }  ],  "meta": {    "page": 1,    "limit": 20,    "total_pages": 3,    "total_count": 45  }}