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

# List Cognitive Roadmaps

> Retrieve a paginated list of cognitive roadmaps with search and filter support to find multi-test packages by completion state, product type, or participant profile.

Use this endpoint to list all cognitive roadmaps associated with your organizer account. Roadmaps are multi-test packages with AI-powered combined analysis, created from the Braintest user panel. You can search by title or filter by completion status, roadmap product type, and participant profile attributes.

## Endpoint

```http theme={"dark"}
GET https://braintest.ir/api/v2/roadmap/
```

## Query Parameters

<ParamField query="q" type="string">
  Free-text search across roadmap titles, profile names, mobile numbers, and external IDs.
</ParamField>

<ParamField query="page" default="1" type="integer">
  Page number for pagination. Results are paginated at 30 items per page by default.
</ParamField>

<ParamField query="filter__is_finished" type="boolean">
  Filter by completion state. Use `false` to find roadmaps that still need to be started or completed.
</ParamField>

<ParamField query="filter__roadmap__id" type="string">
  Filter by roadmap product identifier, for example `ClinicalWellbeingTriage`.
</ParamField>

<ParamField query="filter__test_records__profile__is_male" type="boolean">
  Filter by the gender of an assigned participant profile.
</ParamField>

<ParamField query="filter__test_records__profile__token" type="string">
  Filter by the UUID of an assigned participant profile.
</ParamField>

<ParamField query="filter__test_records__profile__external_id" type="integer">
  Filter by the partner-assigned external profile ID.
</ParamField>

## Response

<ResponseField name="data.count" type="integer">
  Total number of roadmaps matching the query.
</ResponseField>

<ResponseField name="data.next" type="string | null">
  URL for the next page, or `null` if there are no more pages.
</ResponseField>

<ResponseField name="data.previous" type="string | null">
  URL for the previous page, or `null` on the first page.
</ResponseField>

<ResponseField name="data.results" type="array">
  Array of roadmap list items. Each item includes `token`, `roadmap_id`, `roadmap_title`, `display_title`, `group_id`, `status`, `auth_required`, `tests_auth_required`, `is_finished`, `submit_on`, and `create`.
</ResponseField>

<ResponseField name="data.roadmaps_filter" type="array">
  Available roadmap product types for filtering, each with `id` and `title`.
</ResponseField>

## Example Request

```bash theme={"dark"}
curl -X GET "https://braintest.ir/api/v2/roadmap/?filter__is_finished=false&page=1" \
  -H "API-KEY: YOUR_API_KEY"
```

## Example Response

```json theme={"dark"}
{
  "data": {
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
      {
        "token": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "roadmap_id": "ClinicalWellbeingTriage",
        "roadmap_title": "Clinical Wellbeing Triage",
        "display_title": "Clinical Wellbeing Triage",
        "group_id": "default",
        "status": 2,
        "auth_required": true,
        "tests_auth_required": true,
        "is_finished": false,
        "submit_on": null,
        "create": "2026-08-22T09:00:00Z"
      }
    ],
    "roadmaps_filter": [
      {
        "id": "ClinicalWellbeingTriage",
        "title": "Clinical Wellbeing Triage"
      }
    ]
  },
  "successful": true,
  "messages": []
}
```

## Status Codes in Results

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| 0    | Waiting for organizer VIP or billing action             |
| 1    | Finished with AI analysis                               |
| 2    | Ready to start (no tests submitted)                     |
| 3    | In progress (some tests submitted or profiles assigned) |
| 4    | AI generation queued or processing                      |

## Error Responses

| HTTP | Cause                                              |
| ---- | -------------------------------------------------- |
| 400  | Invalid filter parameter or query                  |
| 401  | Missing or invalid API key                         |
| 403  | Key blocked, API disabled, or prerequisite not met |