Production Results - UserTrace Documentation

Overview

The production counterpart of Simulation Results. Returns production evaluation sessions with their eval outcomes, newest first, whether those conversations arrived as uploaded transcripts or as live traces. No evaluation id required.

Endpoint

GET /api/prod-evaluations/sessions/

Authentication

x-usertrace-api-key: ut_live_YOUR_KEY_HERE

See Authentication.

Query parameters

All filters are optional.

string

Substring match on the evaluation run’s name, e.g. Compliance V3. Case-insensitive.

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.

string

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

string

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

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.

run vs eval: a run is one batch job that scored N evals over M conversations (“Compliance V3”). An eval is a single scoring criterion (“Tone check”). run is the production analogue of simulation on the simulations endpoint.

Example request

curl -X GET "https://api.getusertrace.com/api/prod-evaluations/sessions/?run=Compliance&failed_only=true" \
  -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.

string

Name of the evaluation run this session belongs to.

string

Your own identifier for the conversation: the session id from an uploaded transcript, or the gen_ai.conversation.id you sent with live traces. Use it to correlate results back to your own logs.

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, agent_response. Present only with include_traces=true.

integer

Sessions matching the filters, across all pages.

integer

{
  "items": [
    {
      "url": "https://app.getusertrace.com/production-eval/ca0a2090-...?sessionId=b3e046d3-...",
      "run": "Compliance V3",
      "source_session_id": "814b9f0898",
      "status": "completed",
      "started_at": "2026-07-25T12:30:56.263968+00:00",
      "ended_at": "2026-07-25T12:31:26.072613+00:00",
      "outcome_summary": {
        "total_evaluations": 1,
        "passed_count": 1,
        "failed_count": 0,
        "pass_rate": 1.0
      },
      "eval_outcomes": [
        {
          "eval_name": "Compliance V3: Bias, Hallucination, Policy Handling",
          "eval_category": "compliance",
          "eval_type": "session_level",
          "outcome": "pass",
          "reasoning": "No policy-restricted advice was offered..."
        }
      ]
    }
  ],
  "total": 666,
  "skip": 0,
  "limit": 50
}

Production sessions have no agent, scenario or persona. Those concepts exist only for simulations, so the keys are absent rather than null. Use Simulation Results for simulation runs.

What’s excluded

Sessions with no eval outcomes don’t appear. An evaluation creates one session per uploaded document, and the transcript parser then fans out into child sessions that carry all the outcomes, leaving the parent as a bookkeeping row with nothing to report. total counts only sessions that actually have results.

Failures only

With failed_only=true, outcome_summary still describes the whole session, so len(eval_outcomes) equals outcome_summary.failed_count and is deliberately smaller than total_evaluations.

​Overview

​Endpoint

​Authentication

​Query parameters

​Example request

​Response

​What’s excluded

​Failures only

Overview

Endpoint

Authentication

Query parameters

Example request

Response

What’s excluded

Failures only