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

# Pagination

> Page through Symmetry I-9 list endpoints with the ?page query parameter. Covers which GET endpoints support it, the Pagination-* response headers, and the Link header.

Four list endpoints return results 25 at a time and are paged with the `?page` query parameter. Every paginated response also carries `Pagination-*` headers and a `Link` header, so you can walk through pages without tracking offsets yourself.

## Usage

To request a specific page of results, include the `page` parameter in your query string:

```text theme={null}
https://api.symmetry.com/i9/v1/employers/01971d41-b29d-75cf-a308-15ca267af31c/employees?page=2
```

Page numbers start at 1. If you omit the parameter, the API returns the first page:

```text theme={null}
?page=1
```

Each page contains up to 25 results.

## Supported endpoints

Pagination applies to the following `GET` endpoints:

* `/employers`
* `/employers/{employerId}/employees`
* `/employers/{employerId}/admins`
* `/employers/{employerId}/everifyCases`

<Note>
  `/employers/{employerId}/employees/{employeeId}/submissions` is not paginated. It returns every submission for an employee in a single response, because an employee accumulates only a small number of I-9 submissions over the course of employment.
</Note>

Two of these endpoints also accept filters that narrow the result set before it is paged: `/employees` accepts `status` and `includeStatus`, and `/everifyCases` accepts `actionRequired`. When you filter, the pagination headers describe the filtered set, not the full collection.

## Response headers

Each paginated response includes the following headers to help you navigate pages:

| Header name                     | Header description                             | Example value |
| ------------------------------- | ---------------------------------------------- | ------------- |
| `Pagination-Current-Page`       | The page number returned                       | 2             |
| `Pagination-Current-Page-Items` | Number of results returned on the current page | 2             |
| `Pagination-Page-Item-Limit`    | Page size                                      | 25            |
| `Pagination-Total-Items`        | Total results across all pages                 | 27            |
| `Pagination-Total-Pages`        | Total number of pages                          | 2             |

### Link header

Paginated responses include a `Link` header with page navigation URLs, using the `first`, `prev`, `next`, and `last` relations. The `prev` and `next` relations are only present when a page exists in that direction, so the last page has no `next`:

```text theme={null}
</i9/v1/employers/01971d41-b29d-75cf-a308-15ca267af31c/employees?page=1>; rel="first",
</i9/v1/employers/01971d41-b29d-75cf-a308-15ca267af31c/employees?page=1>; rel="prev",
</i9/v1/employers/01971d41-b29d-75cf-a308-15ca267af31c/employees?page=2>; rel="last"
```

Responses also include a `Link` header pointing to the current request (`self`) along with any parent resources related to the request:

```text theme={null}
</i9/v1/employers/01971d41-b29d-75cf-a308-15ca267af31c/employees>; rel="self",
</v1/employers/01971d41-b29d-75cf-a308-15ca267af31c>; rel="employer"
```

<Tip>
  To retrieve a full collection, request the first page and follow the `next` relation until it is no longer present. This avoids assumptions about page size and keeps working if the record count changes between requests.
</Tip>