All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

Keep reading