> ## 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 Test Records

> List paginated psychological test records with filters for status, test type, profile gender, and more.

Use this endpoint to retrieve a paginated list of test records associated with your organizer account. You can filter by completion status, test type, and profile attributes to locate specific records quickly.

## Endpoint

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

## Headers

| Header    | Value                                 |
| --------- | ------------------------------------- |
| `API-KEY` | Your API key from the organizer panel |

## Query parameters

<ParamField query="q" type="string">
  Free-text search across record metadata.
</ParamField>

<ParamField query="page" default="1" type="integer">
  Page number for pagination. Each page contains 30 items.
</ParamField>

<ParamField query="filter__is_finished" type="boolean">
  Filter by completion status. `true` returns finished records only.
</ParamField>

<ParamField query="filter__test__id" type="string">
  Filter by test identifier, for example `MCMI`, `NEO`, `DASS-21`, or `PHQ-9`.
</ParamField>

<ParamField query="filter__profile__is_male" type="boolean">
  Filter by participant gender. `true` for male, `false` for female.
</ParamField>

<ParamField query="filter__profile__token" type="string">
  Filter by profile UUID token.
</ParamField>

<ParamField query="filter__profile__external_id" type="integer">
  Filter by your own external identifier assigned during profile creation.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <ResponseField name="count" type="integer">
    Total number of records matching the filters.
  </ResponseField>

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

  <ResponseField name="previous" type="string | null">
    URL for the previous page, or `null` if there is no previous page.
  </ResponseField>

  <ResponseField name="results" type="array">
    Array of record objects. Each record includes `token`, `status`, `auth_required`, `tests_auth_required`, `is_finished`, `test`, and `profile`.
  </ResponseField>

  <ResponseField name="records_filter" type="object">
    Summary of available filter options and applied filters.
  </ResponseField>
</ResponseField>

## Example request

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

## Example response

```json theme={"dark"}
{
  "data": {
    "count": 42,
    "next": "https://braintest.ir/api/v2/record/?page=2&filter__is_finished=false&filter__test__id=MCMI",
    "previous": null,
    "results": [
      {
        "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": 2,
        "auth_required": true,
        "tests_auth_required": true,
        "is_finished": false,
        "test": {
          "id": "MCMI",
          "title": "Millon Clinical Multiaxial Inventory"
        },
        "profile": null
      }
    ],
    "records_filter": {
      "is_finished": false,
      "test__id": "MCMI"
    }
  },
  "successful": true,
  "messages": []
}
```