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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.