# List Students

**List Students endpoint**

<mark style="color:green;">`GET`</mark> `/v1/student/list`

This endpoint retrieves a list of students based on various filter criteria. It requires a valid access token and supports multiple query parameters to refine the search results.

**Headers**:

| Name          | Value                   |
| ------------- | ----------------------- |
| Content-Type  | `application/json`      |
| Authorization | `Bearer <access_token>` |

**Query Parameters**

<table><thead><tr><th width="234">Name</th><th width="110">Type</th><th width="289">Description</th><th>Type</th></tr></thead><tbody><tr><td><code>school_slug</code></td><td>string</td><td>The slug identifier for the school to filter students.</td><td>Mandatory</td></tr><tr><td><code>firstname</code></td><td>string</td><td>(Optional) Filter by the student's first name.</td><td>Optional</td></tr><tr><td><code>lastname</code></td><td>string</td><td>(Optional) Filter by the student's last name.</td><td>Optional</td></tr><tr><td><code>sex</code></td><td>string</td><td>(Optional) Filter by the student's gender (e.g., 'male', 'female').</td><td>Optional</td></tr><tr><td><code>start_date</code></td><td>string</td><td>(Optional) Filter students by the start date (format: YYYY-MM-DD).</td><td>Optional</td></tr><tr><td><code>end_date</code></td><td>string</td><td>(Optional) Filter students by the end date (format: YYYY-MM-DD).</td><td>Optional</td></tr><tr><td><code>section_id</code></td><td>string</td><td>(Optional) Filter by the ID of the class section.</td><td>Optional</td></tr><tr><td><code>parent_phone</code></td><td>string</td><td>(Optional) Filter by the parent's phone number.</td><td>Optional</td></tr><tr><td><code>page</code></td><td>number</td><td>(Optional) Page number for pagination (default: 1).</td><td>Optional</td></tr><tr><td><code>size</code></td><td>number</td><td>(Optional) Number of students per page for pagination (default: 5).</td><td>Optional</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
 {
  "result": {
      "id": "number",
      "student_id": "number",
      "code": "string",
      "firstname": "string",
      "middlename": "string",
      "lastname": "string",
      "dob": "string",
      "sex": "string",
      "school_id": "number",
      "family_id": "number",
      "created_at": "string",
      "updated_at": "string"
    }[],
  "page": "number",
  "size": "number",
  "totalPages": "number",
  "totalCount": "number"
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "message": "string",
  "error": "string",
  "statusCode": "number"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dugsi-docs.tiigsi.io/student-endpoints/list-students.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.