Simulation Results - UserTrace Documentation

Overview

Returns simulation sessions with their eval outcomes, newest first. Filter by the agent that was tested and a date range. No simulation id is required, so you can pull results without knowing anything about how a run was set up in the dashboard. Every item deep-links back to the session in the web app.

Endpoint

GET /api/simulations/sessions/

Authentication

x-usertrace-api-key: ut_live_YOUR_KEY_HERE

See Authentication.

Query parameters

All filters are optional. Omit them all and you get every session the key’s owner can see.

string

Substring match on the agent’s name or URL. Case-insensitive.

string

ISO 8601 timestamp. Sessions started at or after this moment.

string

ISO 8601 timestamp. Sessions started at or before this moment.

string

Keep only sessions scored by the named eval, e.g. Tone check. Substring match, case-insensitive.

boolean

default:"false"

Return only sessions with at least one failing eval, showing only the failing outcomes.

boolean

default:"false"

Include the conversation turns for each session.

integer

default:"0"

Number of sessions to skip.

integer

default:"50"

Sessions per page. Capped at 500.

Example request

curl -X GET "https://api.getusertrace.com/api/simulations/sessions/?agent=Support%20Bot&started_after=2026-09-01T00:00:00Z" \
  -H "x-usertrace-api-key: ut_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json"

Response

array

The sessions on this page.

Show Session

string

Deep link to the session in the web app. null in the rare case the simulation row was deleted. The session and its outcomes are still reported.

string

Name of the simulation run this session belongs to.

string

Name of the agent (environment configuration) that was tested.

string

The scenario the simulated user was following.

string

The persona the simulated user adopted.

string

Session status, e.g. completed.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

object

total_evaluations, passed_count, failed_count, pass_rate for the whole session.

array

One entry per eval that scored this session: eval_name, eval_category, eval_type, outcome, reasoning.

array

Conversation turns: session_sequence, user_input, user_reason, agent_response. Present only with include_traces=true.

integer

Sessions matching the filters, across all pages.

integer

{
  "items": [
    {
      "url": "https://app.getusertrace.com/simulation/3d9c49fc-...?sessionId=e076939a-...",
      "simulation": "Nightly regression",
      "agent": "Support Bot v4",
      "scenario": "Customer disputes a duplicate charge",
      "persona": "Frustrated customer",
      "status": "completed",
      "started_at": "2026-09-11T09:20:55.967514+00:00",
      "ended_at": "2026-09-11T09:22:58.845944+00:00",
      "outcome_summary": {
        "total_evaluations": 1,
        "passed_count": 1,
        "failed_count": 0,
        "pass_rate": 1.0
      },
      "eval_outcomes": [
        {
          "eval_name": "Loop Prevention and Conversation Coherence",
          "eval_category": "Safety",
          "eval_type": "session_level",
          "outcome": "pass",
          "reasoning": "The agent acknowledged the dispute and moved to resolution..."
        }
      ]
    }
  ],
  "total": 769,
  "skip": 0,
  "limit": 50
}

traces is omitted entirely unless include_traces=true. It is an absent key rather than an empty list, which would read as “this session had no turns”.

Failures only

failed_only=true keeps sessions with at least one failing eval and publishes only the failing outcomes, which is the shape you want for a CI gate or an alerting job.

curl -X GET "https://api.getusertrace.com/api/simulations/sessions/?failed_only=true&agent=Support%20Bot" \
  -H "x-usertrace-api-key: ut_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json"

total then counts failing sessions, so pagination walks failures rather than sessions.

Each session’s outcome_summary still describes the whole session. So len(eval_outcomes) equals outcome_summary.failed_count and is deliberately smaller than total_evaluations. Don’t compute a pass rate from the array length.

Pagination

Walk pages with skip and limit until skip + len(items) >= total:

curl -X GET "https://api.getusertrace.com/api/simulations/sessions/?skip=50&limit=50" \
  -H "x-usertrace-api-key: ut_live_YOUR_KEY_HERE"

​Overview

​Endpoint

​Authentication

​Query parameters

​Example request

​Response

​Failures only

​Pagination

Overview

Endpoint

Authentication

Query parameters

Example request

Response

Failures only

Pagination