# Add Cursor Pagination to a Ktor API

Yes. An agent adds a keyset-paginated GET /articles to your Ktor service over its existing JDBC code, with a limit cap, a nextCursor field, tests and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-cursor-pagination/ktor/). 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 service talks to its database before it writes a query, because the right pagination shape depends on what the table has to sort by. In a service shaped like the `postgres` sample in ktorio/ktor-samples, `build.gradle.kts` applies `kotlin("jvm") 2.4.20` and `io.ktor.plugin 3.6.0`, depends on `ktor-server-core-jvm`, `ktor-server-content-negotiation-jvm`, `ktor-serialization-kotlinx-json-jvm`, `ktor-server-netty-jvm`, `ktor-server-config-yaml` and `org.postgresql:postgresql:42.7.8`, and sets `jvmToolchain(17)`. The Gradle wrapper is 9.2.1. `src/main/resources/application.yaml` loads `com.example.PostgresApplicationKt.module` on port 8080, and `docker-compose.yaml` starts `postgres:18.0-alpine` with the user, password and `articles` database from `postgres.yaml`.

`ArticleService.kt` uses plain JDBC: its `init` block runs `CREATE TABLE IF NOT EXISTS ARTICLES (ID SERIAL PRIMARY KEY, TITLE VARCHAR(255), BODY VARCHAR(1024))`, and `create`, `read`, `update` and `delete` each prepare one statement inside `withContext(Dispatchers.IO)`. `Routing.kt` exposes `POST /articles`, `GET /articles/{id}`, `PUT /articles/{id}` and `DELETE /articles/{id}`; there is no list route at all, and the `Article` data class carries only `title` and `body`, no id. The serial primary key is the column to paginate on: it is indexed, strictly increasing and never changes, which is what keyset pagination needs and what `OFFSET` does not give.

The agent adds a `list(after: Int?, limit: Int)` method to `ArticleService` that runs `SELECT id, title, body FROM articles WHERE id > ? ORDER BY id LIMIT ?`, asking for `limit + 1` rows so it knows whether another page exists without a second count query. It adds `@Serializable` classes `ArticleSummary(id, title, body)` and `ArticlePage(items, nextCursor)`, where `nextCursor` is the last returned id, or absent when the page was the final one. In `Routing.kt` a new `get("/articles")` parses `limit` (default 20, at most 100, anything else `400 Bad Request`, matching how the existing routes answer a bad `id`) and `after`, calls the service and responds with the page. The existing `Article` class and the four routes are untouched, so current clients keep working.

The sample ships no tests under `src/test`, though `ktor-server-test-host-jvm` and `kotlin-test-junit` are already declared. The agent adds `src/test/kotlin/com/example/PaginationTest.kt` using `testApplication`, wiring `configureSerialization()` and `configureRouting()` against a Postgres it starts in the sandbox with `docker compose up -d`, inserts 25 articles through `POST /articles`, then walks `GET /articles?limit=10` and follows `nextCursor` twice, asserting the ids are increasing, that no article repeats across pages and that the last page has no cursor. It runs `./gradlew build` and `./gradlew test`, then starts the server with `./gradlew run` and pastes two `curl` pages 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 this Ktor service and open a pull request. Read build.gradle.kts, gradle.properties, src/main/resources/application.yaml, postgres.yaml, docker-compose.yaml, src/main/kotlin/com/example/PostgresApplication.kt, src/main/kotlin/com/example/plugins/Routing.kt, src/main/kotlin/com/example/service/ArticleService.kt and src/main/kotlin/com/example/models/Article.kt first. Add a list method to ArticleService that selects id, title and body where id is greater than an optional cursor, ordered by id, fetching limit plus one rows to detect a next page. Add serializable ArticleSummary and ArticlePage classes, the latter with items and an optional nextCursor holding the last id. Add GET /articles to Routing.kt taking limit (default 20, maximum 100, 400 otherwise) and after. Keep the existing Article class and the four existing routes unchanged. Start Postgres with docker compose in the sandbox, add src/test/kotlin/com/example/PaginationTest.kt with testApplication that inserts 25 articles and walks the pages asserting increasing ids, no repeats and no cursor on the last page. Run ./gradlew build and ./gradlew test, start the server, curl two pages and paste them in the pull request.",
  "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

What comes back is a pull request that adds a `list` method and one new SQL constant to `ArticleService.kt`, two data classes next to `Article.kt`, a `get("/articles")` block in `Routing.kt`, and a new `PaginationTest.kt`. The description shows the `./gradlew test` summary and two `curl` responses, the first with a `nextCursor` and the second, fetched with `?after=`, continuing from it.

A repository that runs the samples' `build-all.sh` on pull requests, as `.github/workflows/build-all.yml` does with JDK 24, builds and tests this module there, so a compile error or a failing assertion shows up on the pull request. The list route has no coverage anywhere else, so the new test and the pasted responses are the evidence for it.

A reviewer checks that the query uses `WHERE id > ?` rather than `OFFSET`, that `limit` is capped so a client cannot ask for the whole table, that `nextCursor` is omitted rather than set to zero on the last page, and that the response leaves the `title` and `body` fields exactly as the single-article route returns them. Then they decide whether the cursor should stay a plain id or be encoded before the API is public.

## Run it on every new list endpoint

A team that wants every list endpoint in its Ktor services paginated the same way sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own service class, so a service on Exposed or a different driver gets the same keyset query in that library's syntax, and each opens its own pull request.

Send a `request_id` with each body so a retry returns the run already started. With a `webhook_url` on the API key, Rush POSTs `run.completed` when each turn ends, with a `session_url` to read the pull request from, so the team reviews the pull requests together rather than polling.

## Why run it on Rush?

Pagination bugs hide at the boundaries: the last page, a page that is exactly full, an id that was deleted between two requests. Those only show against a real database with real rows, and a sandbox on Rush has one: the agent runs `docker compose up -d` for the Postgres this service already describes, inserts rows through the service's own routes and walks the pages, with every command and response kept in the run's record.

The result carries its own proof. `./gradlew test` output and two consecutive `curl` pages sit in the pull request, so a reviewer sees the cursor hand-off instead of reasoning about it from the diff. The same request body works unchanged on any Ktor service a team runs, and several run at once in their own sandboxes.

## Frequently asked questions

### Why keyset pagination instead of limit and offset?

With `OFFSET n` Postgres still reads and discards n rows, so page 50 costs fifty times page 1, and a row inserted between requests shifts every later page. `WHERE id > ? ORDER BY id LIMIT ?` uses the primary key index directly and is stable across inserts. The `id SERIAL PRIMARY KEY` in `ArticleService.kt` is exactly the column this needs.

### Does it change the existing routes?

No. `POST /articles`, `GET /articles/{id}`, `PUT /articles/{id}` and `DELETE /articles/{id}` keep their handlers and the `Article(title, body)` class. The list route returns an `ArticleSummary` that adds `id`, because a client cannot follow a cursor without it.

### How does the test get a database?

The sample's `docker-compose.yaml` already defines a `postgres:18.0-alpine` service with the credentials in `postgres.yaml`. The agent starts it in the sandbox before `./gradlew test`, and the test wires `configureRouting` to that connection through `testApplication`; a reviewer runs the same two commands locally.

### Why is the cursor a plain id?

Because the sample has one table and one sort order, an integer cursor is honest and debuggable. If the API becomes public and the team would rather not expose row ids, the pull request notes the one place to base64-encode the value and the one place to decode it.

## More Ktor jobs

- [Add Flyway Migrations to a Ktor App](https://getrush.ai/run/add-flyway-migrations/ktor/)
- [Add Graceful Shutdown to a Ktor Server](https://getrush.ai/run/add-graceful-shutdown/ktor/)
- [Add Health Check Endpoints to a Ktor Server](https://getrush.ai/run/add-health-checks/ktor/)

## The same job on other stacks

- [Add Cursor Pagination to a Litestar API](https://getrush.ai/run/add-cursor-pagination/litestar/)
- [Add Cursor Pagination to a Mongoose and Express API](https://getrush.ai/run/add-cursor-pagination/mongoose/)
- [Add Cursor Pagination to a Prisma API](https://getrush.ai/run/add-cursor-pagination/prisma/)

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