# Add pagination and filtering to list endpoints that return everything

Endpoints that return the whole table, given pagination and filtering before the table gets large.

Category: API surface and contracts
Source: https://letsship.ai/use-cases/add-pagination-and-filtering
Published: 2026-08-25

## Goal

Add pagination and filtering to list endpoints that currently return every row.

## Acceptance criteria

- Pagination follows the project's existing convention
- Tests cover the first page, the last page, and an empty result
- Filtering is validated and cannot be used to scan the whole table
- Existing consumers keep working, through a default or a version

## What lands as proof

Contract tests at the boundaries, which is where off-by-one pagination bugs actually live.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Paginate the {group} list endpoints

Description: Add pagination and filtering to list endpoints that currently return every row.

Acceptance criteria:
- Pagination follows the project's existing convention
- Tests cover the first page, the last page, and an empty result
- Filtering is validated and cannot be used to scan the whole table
- Existing consumers keep working, through a default or a version

Before you create the issue, find list endpoints in this repository with no limit and replace {group} with them.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: add pagination and filtering to list endpoints that currently return every row. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means contract tests at the page boundaries and on the empty page, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.