> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getusertrace.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulation Results

> Fetch simulation sessions and their eval outcomes

## 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

```http theme={null}
x-usertrace-api-key: ut_live_YOUR_KEY_HERE
```

See [Authentication](/api-reference/authentication).

## Query parameters

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

<ParamField query="agent" type="string">
  Substring match on the agent's **name or URL**. Case-insensitive.
</ParamField>

<ParamField query="started_after" type="string">
  ISO 8601 timestamp. Sessions started at or after this moment.
</ParamField>

<ParamField query="started_before" type="string">
  ISO 8601 timestamp. Sessions started at or before this moment.
</ParamField>

<ParamField query="eval" type="string">
  Keep only sessions scored by the named eval, e.g. `Tone check`. Substring match,
  case-insensitive.
</ParamField>

<ParamField query="failed_only" type="boolean" default="false">
  Return only sessions with at least one failing eval, showing only the failing outcomes.
</ParamField>

<ParamField query="include_traces" type="boolean" default="false">
  Include the conversation turns for each session.
</ParamField>

<ParamField query="skip" type="integer" default="0">
  Number of sessions to skip.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Sessions per page. Capped at 500.
</ParamField>

## Example request

```bash theme={null}
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

<ResponseField name="items" type="array">
  The sessions on this page.

  <Expandable title="Session">
    <ResponseField name="url" type="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.
    </ResponseField>

    <ResponseField name="simulation" type="string">
      Name of the simulation run this session belongs to.
    </ResponseField>

    <ResponseField name="agent" type="string">
      Name of the agent (environment configuration) that was tested.
    </ResponseField>

    <ResponseField name="scenario" type="string">
      The scenario the simulated user was following.
    </ResponseField>

    <ResponseField name="persona" type="string">
      The persona the simulated user adopted.
    </ResponseField>

    <ResponseField name="status" type="string">
      Session status, e.g. `completed`.
    </ResponseField>

    <ResponseField name="started_at" type="string">ISO 8601 timestamp.</ResponseField>
    <ResponseField name="ended_at" type="string">ISO 8601 timestamp.</ResponseField>

    <ResponseField name="outcome_summary" type="object">
      `total_evaluations`, `passed_count`, `failed_count`, `pass_rate` for the **whole**
      session.
    </ResponseField>

    <ResponseField name="eval_outcomes" type="array">
      One entry per eval that scored this session: `eval_name`, `eval_category`,
      `eval_type`, `outcome`, `reasoning`.
    </ResponseField>

    <ResponseField name="traces" type="array">
      Conversation turns: `session_sequence`, `user_input`, `user_reason`,
      `agent_response`. Present only with `include_traces=true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Sessions matching the filters, across all pages.
</ResponseField>

<ResponseField name="skip" type="integer" />

<ResponseField name="limit" type="integer" />

```json theme={null}
{
  "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
}
```

<Note>
  `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".
</Note>

## 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.

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## Pagination

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

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