# Add Cursor Pagination to an Echo API

Yes. An agent adds a cursor parameter beside limit and offset on your Echo article listings, keyed on created_at and id, updates tests and Swagger, and opens a PR.

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

## What the agent does

The agent reads how the listings page today. In an API laid out like xesina/golang-echo-realworld-example-app, `handler/article.go` has two list handlers, `Articles` and `Feed`, that read `offset` and `limit` with `strconv.Atoi`, default them to 0 and 20 on any parse error, and call one of `List`, `ListByTag`, `ListByAuthor`, `ListByWhoFavorited` or `ListFeed` on the `article.Store` interface in `article/article.go`. Each of those methods in `store/article.go` runs a GORM v1 query with `Preload` for favorites, tags and author, `Offset(offset)`, `Limit(limit)` and `Order("created_at desc")`, and a separate `Count` for the total. `model.Article` embeds `gorm.Model`, so every row has `ID` and `CreatedAt`. `handler/response.go` builds an `articleListResponse` of `articles` and `articlesCount`. The handlers carry `@Param limit` and `@Param offset` annotations for swag, and `docs/docs.go`, `docs/swagger.json` and `docs/swagger.yaml` are the generated output checked in. `handler/article_test.go` lists articles from two fixtures and asserts `articlesCount` is 2.

The cursor sits beside the old parameters rather than replacing them, because the RealWorld clients that call this API send `offset`. The agent adds an optional `cursor` query parameter: an opaque string that is the base64 of `created_at` in RFC 3339 with nanoseconds and the `id`, joined by a separator. When `cursor` is present the store ignores `offset` and adds `WHERE (created_at, id) < (?, ?)`, written as `created_at < ? OR (created_at = ? AND id < ?)` because the SQLite build the tests use does not compare row values the same way everywhere, and keeps `Order("created_at desc, id desc")` so two articles created in the same second have a stable order. It asks for `limit + 1` rows, and if it gets them, drops the last one and returns the cursor of the new last row as `nextCursor` in the response; otherwise `nextCursor` is absent.

The interface changes in one place. Each list method on `article.Store` takes a `ListParams` struct with `Offset`, `Limit` and `Cursor` instead of two ints, which touches the five store methods, the five call sites in the handler and nothing else, and a `cursor.go` file in the `store` package encodes and decodes the value and returns an error the handler turns into a 400 with the existing `utils.NewError`. `articleListResponse` gains `NextCursor string` with `json:"nextCursor,omitempty"`, so clients that never send a cursor see an unchanged body. The `@Param` annotations gain a `cursor` line and the agent runs `swag init` with the pinned v1.6.5 so the three generated files move together.

The check is the handler suite and a walk through the pages. The agent adds a third and fourth fixture article in `handler/handler_test.go`, two of them with the same `CreatedAt`, and tests that `?limit=2` returns a `nextCursor`, that following it returns the remaining rows with none of the first page repeated, that a tampered cursor returns 400, and that `offset` still works when no cursor is sent. It runs `go build -v ./...` and `go test -v ./...`, the two commands in `.github/workflows/go.yml`, and quotes both in the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add cursor pagination to the article listings of this Echo API. Read handler/article.go, handler/response.go, handler/article_test.go, handler/handler_test.go, article/article.go, store/article.go, model/article.go, main.go and .github/workflows/go.yml first. Keep limit and offset working. Add an optional cursor query parameter that is the base64 of the last article's created_at and id; when present, ignore offset and filter with created_at < ? OR (created_at = ? AND id < ?), order by created_at desc, id desc, fetch limit plus one rows, and return nextCursor in the list response only when another page exists. Replace the offset and limit ints on the article.Store list methods with a ListParams struct and update the five store methods and their handler call sites. Put the cursor encoding and decoding in store/cursor.go and answer a malformed cursor with a 400 through utils.NewError. Add a cursor @Param annotation to both list handlers and regenerate docs/ with the pinned swag version. Add fixtures with equal created_at values and tests for a two-page walk with no repeats, a tampered cursor and the offset path. Run go build -v ./... and go test -v ./... and open a pull request that quotes both.",
  "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 changes `article/article.go`, `store/article.go`, `handler/article.go`, `handler/response.go`, the two test files and the three generated files under `docs/`, and adds `store/cursor.go`. Its description shows a two-request walk, the first with `?limit=2` and its `nextCursor`, the second with that cursor and no `nextCursor`, and quotes the `go build` and `go test` output.

A reviewer checks that the cursor is opaque to clients and rejected when tampered, that the order clause includes `id` so equal timestamps page correctly, that the offset path is byte-for-byte what it was, and that `docs/` was regenerated rather than edited. They may want `articlesCount` dropped from cursor responses to save the `Count` query, which the pull request leaves in for compatibility and names as the follow-up.

Clients that send `cursor` get stable pages that do not skip or repeat when articles are inserted between requests; clients that send `offset` get what they got before.

## Run it on every Linear issue labelled api-pagination

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `api-pagination` starts a read-only run that reads the issue and posts its plan as a comment: which handlers, which store methods, which tests. The change starts from the reader's own server, which sends this body to `POST /o/{org}/sessions` with the issue's URL in `resources` beside the repository so the issue text is in the prompt, and a `request_id` that is a UUID v5 of the issue id, so a retried call returns the run it already started.

Each run reads that service's own store, so a listing on Postgres gets a row-value comparison in one clause, one that orders by `updated_at` gets a cursor on that column, and one with no total count never had one to keep.

## Why run it on Rush?

Cursor pagination is easy to get subtly wrong: a cursor on `created_at` alone skips rows that share a second, an order clause without the tiebreaker returns them in a different order on each query, and an offset path that changed shape breaks every existing client. The agent writes the fixtures that expose each of those, runs the suite in its own sandbox with the project's own Go version, and keeps the output with the pull request.

A company with several Go services lists things in each of them. The same request runs across all of them at once, each in its own sandbox, and each pull request fits that service's store and ordering while sharing one cursor format clients can learn once.

## Frequently asked questions

### Does offset still work?

Yes. A request without `cursor` runs the same `Offset` and `Limit` query as before and returns the same body. The cursor path only applies when the parameter is present, and the tests cover both.

### What is inside the cursor?

The last article's `created_at` and `id`, base64-encoded. Clients treat it as opaque and send it back unchanged; a value that does not decode, or decodes to anything other than a timestamp and an integer, gets a 400.

### Why order by id as well as created_at?

Two articles created in the same second have equal `created_at` values, and a cursor on that column alone would skip one of them or return it twice. `id` is unique and monotonic, so `(created_at, id)` is a total order and the tiebreaker makes the walk stable.

### Why change the Store interface?

Five methods took the same two ints and would each need a third parameter. A `ListParams` struct touches the same five signatures once and leaves room for a sort direction later without another round of edits.

### Will the Swagger page show the new parameter?

Yes. The handlers' `@Param` annotations gain a `cursor` line and the agent regenerates `docs/` with the swag version pinned in `go.mod`, so `/swagger/` reflects it without a hand edit to the generated files.

## More Echo jobs

- [Add Versioned Database Migrations to an Echo App](https://getrush.ai/run/add-database-migrations/echo/)
- [Add Dependabot to an Echo App](https://getrush.ai/run/add-dependabot/echo/)
- [Add golangci-lint to an Echo API's CI](https://getrush.ai/run/add-golangci-lint-to-ci/echo/)

## The same job on other stacks

- [Switch a Fastify API From Offset to Cursor Pagination](https://getrush.ai/run/add-cursor-pagination/fastify/)
- [Add Cursor Pagination to a Gin API from a Linear Issue](https://getrush.ai/run/add-cursor-pagination/gin/)
- [Add Cursor Pagination to a GORM API](https://getrush.ai/run/add-cursor-pagination/gorm/)

## 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/)
