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

# Record and Roadmap Status Code Reference

> Learn the status codes for Braintest records and roadmaps, what each state means, and the correct next step for each.

Braintest uses numeric status codes to communicate the lifecycle state of records (standalone tests) and roadmaps (multi-test packages). This page lists every code, explains what it means, and tells you what action to take next.

## Record status codes

Records represent individual psychological test instances such as MCMI, NEO, DASS-21, or PHQ-9.

| Status | Name     | Meaning                                                | Next step                                                                                   |
| ------ | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| 0      | VIP wait | The record is reserved and waiting for VIP processing. | No action needed. The platform will update the status automatically.                        |
| 1      | Finished | The test is complete and results are available.        | Retrieve results via `/record/{token}/result/json/` or `/result/html/`.                     |
| 2      | Ready    | The record is active and can be started.               | Authenticate the profile if `auth_required: true`, then fetch questions and submit answers. |

## Roadmap status codes

Roadmaps are multi-test packages that combine several records into a single AI-powered analysis.

| Status | Name             | Meaning                                                                        | Next step                                                                            |
| ------ | ---------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| 0      | VIP wait         | The roadmap is reserved and waiting for VIP processing.                        | No action needed. The platform will update the status automatically.                 |
| 1      | Finished with AI | All tests are complete and the AI analysis is ready.                           | Retrieve results via `/roadmap/{token}/result/json/` or `/result/html/`.             |
| 2      | Ready            | The roadmap is active and can be started.                                      | Authenticate profiles, complete each test record, then request AI generation.        |
| 3      | In progress      | At least one test record has been started but the roadmap is not yet complete. | Continue completing the remaining test records.                                      |
| 4      | AI processing    | All tests are finished and the AI analysis is being generated.                 | Poll `/roadmap/{token}/generate/status/` until the state is `completed` or `failed`. |

## Gender codes

Gender appears in three places across the API. Use the values consistently.

| Field               | Type           | Values                          | Notes                                                         |
| ------------------- | -------------- | ------------------------------- | ------------------------------------------------------------- |
| `is_male`           | boolean        | `true` or `false`               | Required in profile objects. `true` = male, `false` = female. |
| Role `gender`       | string         | `"male"` or `"female"`          | Specifies the expected gender for a roadmap role.             |
| `gender_permission` | string or null | `"male"`, `"female"`, or `null` | Test-level restriction. `null` means no restriction.          |

When `gender_permission` is set on a record, the participant's profile gender must match the permission value or the API returns a `403` error.

## Pagination

List endpoints return paginated results with 30 items per page.

| Parameter  | Type         | Description                                            |
| ---------- | ------------ | ------------------------------------------------------ |
| `page`     | integer      | The page number to fetch. Defaults to 1.               |
| `next`     | string (URL) | URL for the next page, or `null` if there is none.     |
| `previous` | string (URL) | URL for the previous page, or `null` if there is none. |

**Example paginated response snippet**

```json theme={"dark"}
{
  "data": {
    "count": 87,
    "next": "https://braintest.ir/api/v2/record/?page=2",
    "previous": null,
    "results": [
      { "token": "abc123", "status": 2, "auth_required": true }
    ]
  },
  "successful": true,
  "messages": []
}
```

To navigate pages, pass `?page=N` as a query parameter:

```bash theme={"dark"}
curl -X GET "https://braintest.ir/api/v2/record/?page=3" \
  -H "API-KEY: YOUR_API_KEY"
```

## Related pages

* [Run a standalone test](/guides/run-standalone-test): step-by-step guide for working with records
* [Run a cognitive roadmap](/guides/run-cognitive-roadmap): step-by-step guide for working with roadmaps
* [API error reference](/reference/errors): how to handle errors when status checks fail