# Add Cursor Pagination to a chi API from a Linear Issue

Yes. Label the Linear issue and an agent replaces offset paging in your chi list handler with a keyset cursor, fixes the limit parsing on the way, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-cursor-pagination/chi/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts from the Linear issue and the repository in its own sandbox, and reads the list handler the issue names before touching it. In an API laid out like dhax/go-base, `GET /admin/accounts` is `list` in `api/admin/accounts.go`: it calls `database.NewAccountFilter(r.URL.Query())`, hands the filter to `AdmAccountStore.List` in `database/admAccountStore.go`, and answers `accountListResponse` with an `accounts` array and a `count`. `AccountFilter.Apply` turns the filter into a bun query with `Limit`, `Offset`, one `Where("? = ?", bun.Ident(key), value)` per leftover query parameter and an `Order` per `order` value, and `List` runs it with `ScanAndCount`, so every page costs a full count of the matching rows. The `accounts` table from `database/migrations/1_initial.go` has a serial `id` primary key, `created_at`, `email` (unique), `name`, `active` and `roles`, and `go.mod` pins `uptrace/bun` v1.2.15 and `go-chi/chi/v5` v5.4.0.

Reading `NewAccountFilter` it finds a bug the issue did not mention: `f.Limit = int(limit[0] - '0')` and the same line for `offset` parse only the first character, so `?limit=25` asks for 2 rows and `?limit=100` asks for 1. The agent fixes both with `strconv.Atoi`, keeps the default of 10, caps `limit` at 100 and answers a 400 through the existing `ErrRender` path for anything that is not a positive integer. It says in the pull request that this is a behavior change for any client that relied on the old parsing, and that `offset` stays supported for one release so existing callers keep working while they move.

The cursor itself is keyset on `id`: an `after` query parameter carrying a base64url string that decodes to the last `id` of the previous page. `Apply` adds `Where("id > ?", afterID)`, forces `Order("id ASC")` and asks for `limit + 1` rows; `List` drops the extra row and reports whether there was one. The agent keeps `ScanAndCount` only for the first page, where `count` still reports the total, and uses `Scan` for cursor pages, which is the point of the change. A request that sends both `after` and `order` is refused with a 400, because an arbitrary sort order and a keyset on `id` cannot both hold, and the pull request explains why rather than silently ignoring one. The response gains a `next` field with the encoded cursor, built in `newAccountListResponse`, and the agent leaves the `accounts` array as it is so a client that ignores `next` still reads the first page it always read. A tampered cursor that does not decode answers 400 like a bad `{accountID}` does in `accountCtx`.

The `AccountStore` interface in `api/admin/accounts.go` is already mocked-shaped, so the agent adds `api/admin/accounts_test.go` on the pattern of `auth/pwdless/api_test.go`: an `httptest.Server` with the admin router, a fake store that returns a fixed slice, and cases for `limit=25` now meaning 25, the `after` cursor round trip, the capped limit, the rejected `after` plus `order` combination and a garbage cursor. For the real query it installs Postgres with `apt-get` in its sandbox, runs `go run main.go migrate`, starts `go run main.go serve`, creates a few accounts through `POST /admin/accounts` with the bootstrap admin from `database/migrations/2_bootstrap_users.up.sql`, and walks `/admin/accounts?limit=2` by following `next` until it is empty. It runs `go test -v ./...`, the command `.github/workflows/test.yml` runs, and regenerates `routes.md` with `go run main.go gendoc -r`, which lists every route and its middleware from the router, so the generated file matches the code.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace offset pagination on the admin accounts list in this chi API with a keyset cursor. Read api/admin/accounts.go, api/admin/api.go, database/admAccountStore.go, database/migrations/1_initial.go, database/migrations/2_bootstrap_users.up.sql, auth/pwdless/api_test.go, cmd/gendoc.go, routes.md and go.mod first. NewAccountFilter parses limit and offset from their first character only; fix both with strconv.Atoi, keep the default limit of 10, cap it at 100 and answer 400 on anything that is not a positive integer. Add an after parameter, a base64url cursor holding the last id, that adds where id greater than the cursor, forces order by id ascending and asks for limit plus one rows; refuse a request that sends both after and order with a 400 and say why in the pull request. Keep ScanAndCount and the count field for the first page only. Add a next field with the encoded cursor to the list response and leave the accounts array unchanged. Keep offset working for one release and say so. Write api/admin/accounts_test.go with an httptest server and a fake AccountStore covering the limit fix, the cursor round trip, the cap, the refused after plus order, and a garbage cursor. Install Postgres in your sandbox, run the migrations, start the server, create accounts as the bootstrap admin, walk /admin/accounts?limit=2 by following next, and paste the walk and go test -v ./... into the pull request. Regenerate routes.md with go run main.go gendoc -r. Change nothing in create, get, update or delete.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request links the Linear issue, changes `database/admAccountStore.go` and `api/admin/accounts.go`, adds `api/admin/accounts_test.go` and updates `routes.md`. Its description pastes the `go test -v ./...` output, the `curl` walk of `/admin/accounts?limit=2` with the `next` value from each page fed into the following request and an empty `next` on the last, and the SQL bun ran, which this service prints when started with `--db_debug` because `DBConn` adds the `bundebug` hook, so the reviewer sees the `WHERE id > ?` and `LIMIT 3` in the statement that ran.

The first page of `/admin/accounts` with no parameters answers what it always answered, plus `next`. The visible changes are that `limit=25` now returns 25 rows rather than 2, that a limit over 100 is capped, and that a cursor page skips the count query. The description lists each of these as a line a reviewer can disagree with.

Before merging, a reviewer decides whether `offset` should go now or after the deprecation period the agent wrote in, whether `count` on the first page is worth its query, and whether an `id` cursor is the order their admin client wants or whether a `created_at` keyset, which needs a composite `(created_at, id)` cursor and an index to match, should be the follow-up the pull request describes.

## Run it on every Linear issue labelled agent

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled` with the label you reserve for the agent in its `labels`. Each labelled issue starts one run with the issue as its context, on its own branch, and the trigger adds the issue after the prompt rather than filling in a placeholder; a change made by an app integration never fires it, so a comment the agent posts on the issue does not start a second run.

The automation's `max_runs_per_hour` cap holds a label applied across a backlog to that many runs an hour: a fire past it is created `queued` and starts once the hour has room, and one past a second hour's worth is skipped as `rate_limited` until the issue is labelled again. From your own server, the same run starts with this request and the issue URL in `resources`, and a `request_id` that is a UUID v5 of the issue id makes a retried start return the run already began.

## Why run it on Rush?

A cursor change is small in the diff and large in what can go wrong: a `limit + 1` off by one, a cursor on a column that is not unique, an `order` parameter that silently breaks the keyset, and in this codebase a limit parser that was already wrong. The agent proves each case against the real service in its own sandbox, with Postgres installed, the migrations applied and the pages walked with `curl`, and the pull request carries that walk rather than a promise.

The transcript keeps every command and its output, so the reviewer reads the SQL that ran, the headers each page returned and the test summary without checking the branch out. Several list endpoints across services can be converted at once, each run in its own sandbox with its own database, and nothing merges until a person reads the diff.

## Frequently asked questions

### Why fix the limit parsing when the issue only asked for a cursor?

Because the cursor is built on `limit`, and `limit[0] - '0'` reads one digit, so `limit=25` would page in twos. Leaving it would make the new `next` links wrong on the first request. The fix is three lines with `strconv.Atoi`, it is covered by the new test, and the pull request lists it as its own behavior change so a reviewer can object.

### Why is the cursor on id rather than created_at?

A keyset must be on a unique, indexed ordering, or rows that share a value at a page boundary are skipped or repeated. `id` is the serial primary key of `accounts`. `created_at` defaults to the insert time and is not unique, so a keyset on it needs a composite `(created_at, id)` cursor and a matching index, which the pull request names as the next step rather than guessing at the order your admin client wants.

### What happens to clients that send offset?

They keep working for one release: `offset` is still parsed, now correctly, and applied when no `after` is present. The response carries `next` either way, so a client can switch when it is ready. The pull request says which release removes `offset`, and that line is for the reviewer to change.

### Why refuse after together with order?

The cursor encodes a position in an `id` ordering. If a client also asks for `order=name`, the `id > ?` condition no longer means the next page, it means an arbitrary subset. Answering 400 with a message is clearer than returning rows that look like a page and are not.

### Does it touch the other filter parameters?

No. The equality filters that `Apply` builds from leftover query parameters, such as `active=true`, still apply on every page, including cursor pages, because the `id > ?` condition is added beside them rather than in place of them. The test for the cursor round trip sends a filter too, so that combination is covered.

## More chi jobs

- [Add Graceful Shutdown to a Go chi API](https://getrush.ai/run/add-graceful-shutdown/chi/)
- [Add Health Checks to a chi API](https://getrush.ai/run/add-health-checks/chi/)
- [Add HTTP Server Timeouts to a chi API](https://getrush.ai/run/add-http-timeouts/chi/)

## The same job on other stacks

- [Add Cursor Pagination to a Cloudflare Worker on D1](https://getrush.ai/run/add-cursor-pagination/cloudflare-workers/)
- [Add Cursor Pagination to a Django REST Framework API from a Linear Issue](https://getrush.ai/run/add-cursor-pagination/django-rest-framework/)
- [Add Cursor Pagination to a Drizzle API](https://getrush.ai/run/add-cursor-pagination/drizzle/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
