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

# Session API

> REST endpoint to fetch a single session with its timeline and incidents

The Session API gives REST access to a Proctoring v8 session: the session itself, its chronological timeline, and the incidents raised during it, including the events behind each incident.

## Conventions

* **Base URL.** `https://api.talview.com`
* **GET only.** The endpoint is a read and takes no request body.
* **Bearer authentication.** Send an access token in the `Authorization` header. See [Authentication](https://docs.talview.com/graph-api-reference/authentication.md).
* **Automatic tenant isolation.** The tenant comes from the token. Never send a `tenant_id` parameter. A session that belongs to another tenant is reported as not found.
* **UTC timestamps** in ISO 8601 format throughout.

```javascript theme={null}
headers: {
  "Authorization": "Bearer <Access_Token>"
}
```

## Get a session

`GET /api/rest/sessions/{uuid}`

Fetches one session by its Talview-issued UUID. Store the `uuid` returned for each session and use it as your reference: sessions cannot be looked up by an external candidate identifier.

### Path parameters

| Parameter | Type | Description |
| - | - | - |
| `uuid` | string (UUID) | The session's UUID. |

### Response

```json theme={null}
{
  "__typename": "session_instance",
  "id": 22279,
  "uuid": "019fb26c-685e-75ab-bd0c-a6c3170537a4",
  "status": "COMPLETED",
  "score": null,
  "summary": [
    {
      "id": "d93b0e9f-c576-4d44-b348-bfc361a31c50",
      "type": "paragraph",
      "props": {
        "textColor": "default",
        "textAlignment": "left",
        "backgroundColor": "default"
      },
      "content": [
        {
          "text": "Screen unauthorized application in background",
          "type": "text",
          "styles": { "bold": true }
        }
      ],
      "children": []
    }
  ],
  "integrity": "NEEDS_REVIEW",
  "created_at": "2026-07-30T09:47:56.948085+00:00",
  "url": "http://localhost:4200/",
  "external_id": "attempt_1234297581",
  "timelines": [
    {
      "__typename": "session_instance_timeline",
      "id": 263653,
      "event_type": "CONSENT_PAGE_SHOWN",
      "event_trigger_at": "2026-07-30T09:48:10.444+00:00",
      "created_at": "2026-07-30T09:48:09.330647+00:00",
      "created_by": 35659447,
      "comment": null,
      "incident_id": null,
      "ca_request_id": null,
      "idv_request_id": null,
      "form_instance_id": null
    }
  ],
  "incident_instances": [
    {
      "__typename": "incident_instance",
      "id": 83730,
      "name": "Unauthorized Background Screen Detected",
      "status": "TRIGGERED",
      "start_time": "2026-07-30T09:49:15+00:00",
      "end_time": "2026-07-30T10:02:27.372+00:00",
      "description": null,
      "severity": "LOW",
      "events": [
        {
          "id": 5120934,
          "type": "UNAUTHORIZED_APPLICATION_DETECTED",
          "timestamp": "2026-07-30T09:49:15+00:00"
        }
      ]
    }
  ]
}
```

### Field notes

| Field | Description |
| - | - |
| `status` | Current [session status](#session-statuses). |
| `score` | The session's Proview Index (shown as "risk" in v8): a 0-1 score from the frequency and severity of incidents. |
| `integrity` | Integrity assessment of the session: `HIGH`, `NEEDS_REVIEW` or `LOW`, or `null` until the session has been assessed. |
| `summary` | AI-generated session summary as rich-text blocks. |
| `external_id` | The `identifier` you supplied when the session was created, or `null`. See the identifier rules in the [`init` options](https://docs.talview.com/sdk/proctoring/configuration#init). |
| `url` | The page origin captured when the session started. **Not a recording link**, and often `null`. |
| `timelines` | Chronological log of session events, earliest first. |
| `incident_instances` | Every incident raised in the session. |
| `incident_instances[].events` | The events that make up the incident. Present in this API only; each event carries `id`, `type` and `timestamp`. |

### Errors

| Status | Cause |
| - | - |
| `404` | The session does not exist, or belongs to another tenant. |
| `422` | `uuid` is not a valid UUID. |

### Session statuses

`CREATED`, `IN_PROGRESS`, `PAUSED`, `STOPPED`, `SUSPENDED`, `COMPLETED`, `TERMINATED`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.