How-to › Move data in and out

How to paginate an API with Go range-over-func iterators#

Expose a cursor-paged list as a Go range-over-func sequence of books and errors that stops on break, on a cancelled context, and on a later page's error.

Audience
API consumer
Level
intermediate
Topic
Paginate collections
Languages
Go
Verified

Read first: Loop over every page of a REST collection

Your list call returns the first page and a nextCursor, and every caller writes the same loop around it. One caller forgets to stop when the loop body is done, and fetches the remaining pages for nothing. Another reads a 500 on page two as the end of the list, and ships a report with a third of the books in it.

What you get

You will end up with a client method that returns an iter.Seq2[Book, error], and tests for the three ways a range loop over it ends. This is for you if you write a Go client for a paged API and want callers to range over every item.

Short answer

Return an iter.Seq2[Book, error] whose function fetches one page, yields each book, and follows the next cursor until there is none. Return as soon as yield returns false, so a break stops the fetching. Check ctx before each request and build the request with it. Yield a failed page or a cancelled context as one last pair with a zero Book. Say in the doc comment that the books before that pair are only part of the list.

You will need

Go 1.23 or later, which runs a range over a function, and an API whose list endpoint returns a next cursor. Verified 2026-11-22 against Go 1.24.7, @voxgig/sdkgen 4.44.3 and Swagger Codegen 3.0.85. The prerequisite page, loop over every page of a REST collection, covers the loop itself.

The document, api.json, has one list operation: GET /books with limit and cursor, answering { items, nextCursor }, where nextCursor is null on the last page. The stand-in in standin/ holds requests to it: a limit outside 1 to 100 or a cursor it never issued is a 400.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
AWS SDK for Go v2 paginatorsYou call AWS, whose SDK ships a paginator for each paginated operationAn explicit HasMorePages and NextPage loop at every call site, page by pageYou want callers to range over items
Fern Go auto-paginationFern generates your Go SDK from a document with x-fern-paginationA Next, Current and Err iterator, and a free plan that covers Python and TypeScript onlyYou need a range loop without an adapter
go-github ListOptions and Iter methodsYou call GitHub from GoA page-number loop on resp.NextPage, or generated Iter methods for GitHub onlyYour API is not GitHub
iter.Seq2 with a yield loopYou write the client, and callers range over itemsA function per list operation, and the three stops to write and test yourselfA generator already writes paging for your API
sdkgen paging featureYou generate several languages and want one paging signal in eachA control map you pass on every call, no context.Context, and a channel streamCallers need cancellation mid-walk
Swagger Codegen go clientYou want a generated Go client from the document with no accountOne page per call, no paging code, and a null cursor typed as stringYou want the generator to page for you

Voxgig maintains sdkgen. The table lists it beside five other ways to page in Go, alphabetically, with no ranking.

The iter.Seq2 route costs a function per list operation and gives callers the loop the language offers. The AWS paginator and Fern’s iterator are both explicit loops, so each caller writes the three stops. go-github’s generated Iter methods already have the shape this page builds. Swagger Codegen’s go client leaves paging to you, and sdkgen pages through a control map at the price of cancellation.

Yield one book at a time, and the error last

Books fetches a page only after the caller has consumed the one before it, so it never has a request in flight that nobody asked for. The doc comment says what a caller must not do with a truncated list.

// Books yields every book on every page, fetching a page only when the
// caller has consumed the one before it.
//
// The sequence ends in one of three ways. It ends after the last book when
// the server sends no next cursor. It ends early, with no further request,
// when the loop body breaks or returns. It ends with a final pair whose error
// is non-nil when a request fails, the context is done, or the server sends a
// cursor it already sent; the books yielded before that pair are only part of
// the list, so a caller that ignores the error must not treat them as
// complete. The error is a *PageError naming the page and its cursor.
func (c *Client) Books(ctx context.Context) iter.Seq2[Book, error] {
	return func(yield func(Book, error) bool) {
		cursor := ""
		seen := map[string]bool{}
		for page := 1; ; page++ {
			if err := ctx.Err(); err != nil {
				yield(Book{}, &PageError{Page: page, Cursor: cursor, Err: err})
				return
			}
			p, err := c.FetchPage(ctx, cursor)
			if err != nil {
				pe, ok := err.(*PageError)
				if !ok {
					pe = &PageError{Err: err}
				}
				pe.Page, pe.Cursor = page, cursor
				yield(Book{}, pe)
				return
			}
			for _, b := range p.Items {
				if !yield(b, nil) {
					return
				}
			}
			if p.NextCursor == nil || *p.NextCursor == "" {
				return
			}
			if seen[*p.NextCursor] {
				yield(Book{}, &PageError{Page: page + 1, Cursor: *p.NextCursor, Err: fmt.Errorf("the server sent a cursor it already sent")})
				return
			}
			seen[*p.NextCursor] = true
			cursor = *p.NextCursor
		}
	}
}

The error belongs in the pair because a range loop has nowhere else to put it. A separate Err() method, read after the loop, is a step a caller can skip without a compiler noticing, while the second variable of the pair is right there in the for clause. Calling yield again after it has returned false is a runtime panic, so every return after a refused yield is there to prevent one.1

Stop on break, on cancel, and on a failed page

cmd/demo runs each ending against a fresh stand-in, three books to a page, and counts the list requests the client sent.

go run ./cmd/demo
every book             b1 b2 b3 b4 b5 b6 b7 b8 b9   requests: 3
break after four       b1 b2 b3 b4                  requests: 2
cancel at b4           b1 b2 b3 b4 b5 b6            requests: 2  last pair: page 3 (cursor "c6"): context canceled
page 2 fails           b1 b2 b3                     requests: 2  last pair: page 2 (cursor "c3"): HTTP 500
page 2 fails, err as _ 4 books, 1 of them with no id, and no error reached the caller

A break after the fourth book means page three is never requested. A cancel at b4 lets the books already fetched through, then ends with context canceled before the third request. A 500 on page two ends with a PageError that names the page and the cursor it was sent with.

The last line is the pitfall. A caller who writes for b, _ := range gets three real books and the zero Book that carried the error, and the loop ends the way a complete one does.

Page with Swagger Codegen and sdkgen

Swagger Codegen’s go client has one ListBooks call per page and no paging code. Its BookPage types the cursor as a plain string, so null and "" both arrive as "":

type BookPage struct {
	Items []Book `json:"items"`
	NextCursor string `json:"nextCursor"`
}

adapters.SwaggerBooks puts the same iter.Seq2 over it, and ends on "". The sdkgen Go target, scaffolded with --feature paging, records the next cursor in a control map passed to every List call. adapters.SdkgenBooks wraps that, and checks ctx only between pages, because the SDK’s calls take no context.Context.

go run ./cmd/compare
Swagger Codegen ListBooks, called once     3 books, NextCursor "c3", err <nil>
Swagger Codegen with adapters.SwaggerBooks 9 books, requests: limit=3 | cursor=c3&limit=3 | cursor=c6&limit=3
sdkgen paging, body field "nextCursor"     9 books, requests: limit=3&page=1 | cursor=c3&limit=3 | cursor=c6&limit=3
sdkgen paging, body field "next"           3 books, requests: limit=3&page=1
  last pair: page 2: hasMore is true and no cursor was recorded (paging map[hasMore:true next:c3])
sdkgen Stream("list")                      3 items from 1 request
sdkgen Stream, 5 left after one item       5 goroutines still parked; with a closed signal, 0
Fern's Next, Current, Err shape, wrapped   b1 b2 b3, then: HTTP 500 on page 2

The page’s document names the field nextCursor because that is a name the paging feature sends back. With the same stand-in answering next, the feature records next and sends nothing on, so the adapter stops with an error where the documented loop would ask for page one again.2 The first request also carries page=1, which api.json does not declare. @voxgig/sdkgen 4.45.0 writes the same Go files, byte for byte.

Stream("list") returns a channel of one call’s items. A caller who stops reading leaves the goroutine behind it parked on a send, five of them for five abandoned streams, unless a signal channel was passed in callopts and closed. The generated REFERENCE.md describes the channel and its last Err item but not signal, which the Go README leaves out too. A break out of an iter.Seq2 needs no such cleanup.

Page with Fern’s Go SDK

Fern reads the paging from the document, through an x-fern-pagination extension on the operation: cursor: $request.cursor, next_cursor: $response.nextCursor and results: $response.items for this one. Its auto-pagination page says the Go SDK then returns a *core.Page[T], whose Iterator() has Next(ctx), Current() and Err(), and whose GetNextPage(ctx) goes page by page. The page shows no range-over-func form.

adapters.FromIterator turns that shape into an iter.Seq2, with Err as the last pair. It was tested against a fake with the documented methods, the last line of the cmd/compare output, because no Fern client was generated. Fern’s pricing page puts Python and TypeScript SDKs on the free plan, and Go among the ten SDK languages of the Enterprise plan. Stainless is left out: its announcement of May 18, 2026 says new signups, projects, and SDKs are no longer available.

Check it worked

node check.mjs
pass  adapters TestFromIterator
pass  adapters TestSdkgenAdapterStops
pass  adapters TestSdkgenAdapterStops/all
pass  adapters TestSdkgenAdapterStops/break
pass  adapters TestSdkgenAdapterStops/cancel
pass  adapters TestSdkgenAdapterStops/cursor_field_named_next
pass  adapters TestSdkgenAdapterStops/later_page_fails
pass  adapters TestSdkgenFirstRequestCarriesPageOne
pass  adapters TestSwaggerAdapterStops
pass  adapters TestSwaggerAdapterStops/all
pass  adapters TestSwaggerAdapterStops/break
pass  adapters TestSwaggerAdapterStops/cancel
pass  adapters TestSwaggerAdapterStops/later_page_fails
pass  books TestAPageWithoutItemsIsAnError
pass  books TestARepeatedCursorIsAnError
pass  books TestBreakStopsFetching
pass  books TestCancelEndsTheSequenceWithTheContextError
pass  books TestErrorOnALaterPageIsTheLastPair
pass  books TestEveryPageInOrder
pass  books TestNoPageIsFetchedAhead
pass  books TestTheStandInRefusesWhatTheDocumentRefuses
pass  books TestYieldAfterFalsePanics
22 tests and subtests, 0 not passed

check.mjs runs go test -json and prints the results in a fixed order, so the summary is the same on every run, and it exits 1 when a package fails to build. Each stop has a test for the hand-written iterator and for both adapters, and each counts the requests the stand-in received. TestNoPageIsFetchedAhead shows that Books never has a request in flight while the loop body runs, so no failed fetch can land behind the caller.

When it goes wrong

A loop over the iterator panics. The message reads range function continued iteration after function for loop body returned false, and it means a yield was called after it returned false, usually because a loop over a page’s items kept going. Return on the first false.

The walk never ends. The server sent a cursor it had sent before, and the client follows it in a circle. Books keeps the cursors it has followed and ends with an error on a repeat.

A caller reports a short list as complete. The error half of the pair was dropped with _, and the loop ended normally. Name the second variable, and reject , _ := range over a sequence that carries errors in review.

When not to do this

Do not wrap a client whose SDK already ranges. go-github v93.0.0 generates ListByOrgIter and its siblings with this page’s yield loop and the error as the last pair. A wrapper only adds a layer to keep in step. That release needs Go 1.26, as its go.mod says.

Do not hide a paging channel behind iter.Seq2 without closing the channel’s signal on every exit, since the sdkgen Stream goroutines stay parked otherwise. Do not use the sdkgen paging feature where a walk must be cancelled mid-request, because its calls take no context. Fern suits a team that already generates its SDKs with Fern and can pay for a plan that includes Go, since its iterator comes with every paged operation and needs one adapter. Swagger Codegen suits a team that wants a Go client from the document with no account at all, and is content to write the loop.

Last verified

Verified 2026-11-22 against Go 1.24.7, Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, and Swagger Codegen 3.0.85 on OpenJDK 21, with golang.org/x/oauth2 v0.30.0 and github.com/antihax/optional v1.0.0 pinned for the Swagger Codegen client. The generators ran once, in record.sh, and their output is committed. Fern was not run, because generating needs a Fern login or Docker. Its Go SDK shape comes from the Current version of its auto-pagination page, and its plans from its pricing page. The go-github method was read at its v93.0.0 tag, from the Go module proxy, in record.sh. Every output block is what the command preceding it printed.

Footnotes

  1. The specification gives the rule in one sentence: if the loop body terminates, such as by a break, yield returns false and must not be called again. It leaves the consequence to the runtime, which in Go 1.24.7 panics with a message naming the range function, as TestYieldAfterFalsePanics records. The Go blog post on range functions, dated August 20, 2024, states what the iterator does, more mildly: when yield returns false, no more values are needed. ↩︎ Back to text

  2. The features reference lists next, cursor and nextCursor among the body fields the feature understands, and says the next call continues from a recorded cursor, or else from nextPage. A body next is recorded under its own name, which is neither of the two the next call reads. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.