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

# Candidates & Sessions

> How candidates move through the assessment process

# 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; the admin only edits the Task phase.

<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 (admin-set time, graded)">
    The only admin-editable phase. 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](/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](/api-reference/sessions#get-session-events) for the full list.