Sessions

A session is a learner’s practice run against a published scenario. TrainerTwin creates the record when practice begins, so the API does not create empty sessions.

List sessions

Combine any of these filters:

Parameter	Description
`userId`	Sessions for one learner
`scenario`	Sessions for one published scenario slug
`status`	`active`, `completed`, or `abandoned`
`from`	Started at or after this ISO 8601 timestamp
`to`	Started at or before this ISO 8601 timestamp
`limit`	Page size, `1`–`100` (default `50`)
`offset`	Records to skip (default `0`)

curl "https://trainertwin.com/api/v1/sessions?userId=user_123&status=completed&from=2026-09-01T00:00:00Z&to=2026-09-30T23:59:59Z&limit=25" \
  --header "x-api-key: $TRAINERTWIN_API_KEY"

Results are sorted by start time, newest first. The response includes pagination metadata — page through by increasing offset until offset >= total:

{
  "sessions": [],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 42
  }
}

The list response contains session metadata without transcript or evidence payloads. Fetch one session for the full result.

Get session results

curl "https://trainertwin.com/api/v1/sessions/session_123" \
  --header "x-api-key: $TRAINERTWIN_API_KEY"

The detail response includes:

Pinned persona, scenario, and domain versions.
Session status and timestamps.
Transcript data when available.
Evidence data when available.

Delete a session

Deletion is a soft delete: the session is hidden from list and detail results, but the record (including transcript and audio) is retained for auditing.

curl "https://trainertwin.com/api/v1/sessions/session_123" \
  --request DELETE \
  --header "x-api-key: $TRAINERTWIN_API_KEY"

A successful deletion returns 204 No Content. Deleted sessions no longer appear in list or detail responses and cannot be restored through the API.

Get started

Guides

Resources

List sessions

Get session results

Delete a session

​List sessions

​Get session results

​Delete a session

List sessions

Get session results

Delete a session