# Pagination
URL: https://docs.awellhealth.com/api-reference/guides/pagination

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).



List queries return results in pages. You control the page with `pagination` parameters and the
order with `sorting` parameters, and the response tells you how many results exist in total so
you can page through them.

## Pagination parameters [#pagination-parameters]

List queries accept a `pagination` argument of type `PaginationParams`:

| Field    | Type   | Description                                     |
| -------- | ------ | ----------------------------------------------- |
| `count`  | `Int!` | The number of results to return (page size).    |
| `offset` | `Int!` | The number of results to skip before this page. |

Pagination is **offset-based**: request the first page with `offset: 0`, the second with
`offset: count`, and so on.

**Two limits worth knowing before you build a loop:**

* **Omitting `pagination` does not return everything.** A list query with no pagination argument
  returns the first 10 results.
* **`count` is capped at 100.** A larger value does not error. The query succeeds and returns 100
  records, so code that asks for 500 and trusts the number it asked for misses data with nothing in
  the response to say so. Page instead: compare `offset + count` against `total_count`.

## Sorting parameters [#sorting-parameters]

List queries also accept a `sorting` argument of type `SortingParams`:

| Field       | Type      | Description           |
| ----------- | --------- | --------------------- |
| `field`     | `String!` | The field to sort by. |
| `direction` | `String!` | `"ASC"` or `"DESC"`.  |

`direction` is a string, not an enum, and the values are **uppercase**. `"asc"` is not the same
thing as `"ASC"`.

**Which fields you can sort by depends on the query, and nested fields are not sortable.** For
`patients`, only top-level profile fields work — `last_name`, `birth_date`, `sex`, `patient_code`
and the like — while something like `address.city` is not supported. `patients` sorts by
`last_name` ascending when you don't pass a `sorting` argument.

## Reading the response [#reading-the-response]

List responses include a `pagination` object of type `PaginationOutput`:

| Field         | Type  | Description                            |
| ------------- | ----- | -------------------------------------- |
| `count`       | `Int` | The number of results in this page.    |
| `offset`      | `Int` | The offset this page started at.       |
| `total_count` | `Int` | The total number of results available. |

Keep increasing `offset` by your page size until `offset + count` reaches `total_count`.

## Example [#example]

```graphql
query PatientsPage($pagination: PaginationParams, $sorting: SortingParams) {
  patients(pagination: $pagination, sorting: $sorting) {
    patients {
      id
    }
    pagination {
      count
      offset
      total_count
    }
  }
}
```

Variables:

```json
{
  "pagination": { "count": 25, "offset": 0 },
  "sorting": { "field": "last_name", "direction": "ASC" }
}
```