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

# Candidate sessions and the assessment phases

> Follow a candidate from invite to reviewed score: what a session records, the statuses an attempt moves through, and the phase model.

# Candidates & Sessions

## Candidates

A **candidate** is a person being evaluated. Candidates are identified by email and scoped to your organization. The same person can take multiple assessments, and each attempt creates a separate session.

Candidates are **not** admin users - they don't log into the admin portal. Instead, they receive a unique link that drops them directly into the assessment workspace.

## Sessions

A **session** represents one candidate's attempt at one assessment. It tracks everything: when they started, what they configured, every message they exchanged with the AI, and the final deliverable they submitted.

### Session lifecycle

```
invited → setup → in_progress → submitted → scoring → scored → reviewed
```

| Status | What's happening |
| - | - |
| `invited` | Candidate received the link but hasn't opened it yet |
| `setup` | Candidate is in the **Explore** phase, orienting and optionally setting up their workspace |
| `in_progress` | Candidate is in the **Task** phase, working on the deliverable with AI assistance |
| `submitted` | Candidate submitted their deliverable (or time expired) |
| `scoring` | The automated scoring engine is evaluating the submission |
| `scored` | Scores are available for admin review |
| `reviewed` | An admin has reviewed and optionally adjusted the scores |

<Note>
  The `setup` status is a legacy name for the **Explore** phase described below. It is a fixed, ungraded orientation window, not an admin-configurable step.
</Note>

### The phase model

Every assessment runs on a fixed three-phase model. Gradient sets the shape of every phase and builds the Task for you.

<Steps>
  <Step title="Explore (fixed 5 minutes, ungraded)">
    A short orientation window. The candidate gets oriented, reads the brief, browses the available data, and (where the assessment permits it) sets up their AI workspace by adding skills, memory, or their agents.md configuration. Nothing here is scored.
  </Step>

  <Step title="Task (time set by Gradient, graded)">
    The candidate works with the AI assistant to complete the task brief: chatting, running tool calls (like creating slides), searching connected data sources, and iterating on the deliverable. A countdown timer is visible, and this is the phase Gradient scores.
  </Step>

  <Step title="Reflection (optional, fixed 10 minutes)">
    When enabled, a short reflection on the work just completed. The prompt is locked and identical for every candidate, so reflections are comparable across candidates and assessments. Reflection Quality feeds the [rubric](/docs/concepts/scoring).
  </Step>
</Steps>

At submission (or when the Task timer runs out and the deliverable auto-submits), Gradient snapshots the AI configuration (skills, memory, agents.md, connected data sources) for scoring.

### Session events

Every action a candidate takes during a session is recorded as a timestamped **event**. Events power session replay in the admin review interface and are used by the scoring engine to evaluate AI usage patterns.

There are 20+ event types covering data source browsing, skill creation, AI interactions, deliverable edits, and more. See the [Sessions API](/docs/api-reference/sessions#get-session-events) for the full list.


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