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

# List Students

> Retrieve a paginated list of all students in your organization

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

## Query Parameters

<ParamField query="search" type="string">
  Search students by username, first name, last name, or email
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination (default: 1)
</ParamField>

## Response

<ResponseField name="count" type="integer">
  Total number of students in your organization
</ResponseField>

<ResponseField name="next" type="string">
  URL for the next page of results (null if no more pages)
</ResponseField>

<ResponseField name="previous" type="string">
  URL for the previous page of results (null if first page)
</ResponseField>

<ResponseField name="results" type="array">
  Array of student objects

  <Expandable title="Student Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the student
    </ResponseField>

    <ResponseField name="username" type="string">
      Student's username
    </ResponseField>

    <ResponseField name="email" type="string">
      Student's email address
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      Student's phone number (nullable)
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Student's first name
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Student's last name
    </ResponseField>

    <ResponseField name="public_report_id" type="string">
      Public UUID for student reports
    </ResponseField>

    <ResponseField name="created" type="string">
      ISO 8601 timestamp of when the student was created
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://api.chessplay.io/api/v1/students/ \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```python Python theme={null}
  import requests

  headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
  response = requests.get(
      "https://api.chessplay.io/api/v1/students/",
      headers=headers
  )
  students = response.json()
  print(f"Total students: {students['count']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.chessplay.io/api/v1/students/', {
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });
  const students = await response.json();
  console.log(`Total students: ${students.count}`);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.chessplay.io/api/v1/students/');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ]);
  $response = curl_exec($ch);
  $students = json_decode($response);
  echo "Total students: {$students->count}\n";
  curl_close($ch);
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "count": 25,
    "next": "https://api.chessplay.io/api/v1/students/?page=2",
    "previous": null,
    "results": [
      {
        "id": 123,
        "username": "FastMalamute",
        "email": "john.doe@example.com",
        "phone_number": "+1234567890",
        "first_name": "John",
        "last_name": "Doe",
        "public_report_id": "abc-123-def-456",
        "created": "2024-01-15T10:30:00Z"
      },
      {
        "id": 124,
        "username": "TalentedSnail",
        "email": "jane.smith@example.com",
        "phone_number": null,
        "first_name": "Jane",
        "last_name": "Smith",
        "public_report_id": "xyz-789-uvw-012",
        "created": "2024-01-16T14:20:00Z"
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "detail": "Authentication credentials were not provided."
  }
  ```
</ResponseExample>

## Search Example

Search for students by name, username, or email:

```bash theme={null}
curl -X GET "https://api.chessplay.io/api/v1/students/?search=john" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

This will return all students where "john" appears in their username, first name, last name, or email.

## Pagination Example

Navigate through pages of results:

```bash theme={null}
# Get first page
curl -X GET "https://api.chessplay.io/api/v1/students/?page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get second page
curl -X GET "https://api.chessplay.io/api/v1/students/?page=2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

<Note>
  The default page size is 10 students per page. All students are automatically filtered to your organization.
</Note>