# 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.

Source: https://voxgig.com/howto/paginate-an-api-with-go-range-over-func

- Audience: api-consumer
- Level: intermediate
- Languages: go
- Verified: 2026-11-22
- Published: 2026-11-22

## 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](https://go.dev/ref/spec#For_range), 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](/howto/loop-over-every-page-of-a-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

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [AWS SDK for Go v2 paginators](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/using.html#using-operation-paginators) | You call AWS, whose SDK ships a paginator for each paginated operation | An explicit `HasMorePages` and `NextPage` loop at every call site, page by page | You want callers to range over items |
| [Fern Go auto-pagination](https://buildwithfern.com/learn/sdks/current/deep-dives/auto-pagination) | Fern generates your Go SDK from a document with `x-fern-pagination` | A Next, Current and Err iterator, and a free plan that covers Python and TypeScript only | You need a range loop without an adapter |
| [go-github ListOptions and `Iter` methods](https://github.com/google/go-github) | You call GitHub from Go | A page-number loop on `resp.NextPage`, or generated `Iter` methods for GitHub only | Your API is not GitHub |
| [`iter.Seq2` with a yield loop](https://pkg.go.dev/iter) | You write the client, and callers range over items | A function per list operation, and the three stops to write and test yourself | A generator already writes paging for your API |
| [sdkgen paging feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | You generate several languages and want one paging signal in each | A control map you pass on every call, no `context.Context`, and a channel stream | Callers need cancellation mid-walk |
| [Swagger Codegen go client](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/about/) | You want a generated Go client from the document with no account | One page per call, no paging code, and a null cursor typed as `string` | You 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.

```go title="books/books.go"
// 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.

```bash
go run ./cmd/demo
```

```text output
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 `""`:

```go title="generated/swaggergo/model_book_page.go"
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`.

```bash
go run ./cmd/compare
```

```text output
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`](https://buildwithfern.com/learn/sdks/current/deep-dives/auto-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](https://buildwithfern.com/pricing) 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](https://www.stainless.com/blog/stainless-is-joining-anthropic/)
of May 18, 2026 says new signups, projects, and SDKs are no longer available.

## Check it worked

```bash
node check.mjs
```

```text output
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`](https://github.com/google/go-github/blob/v93.0.0/github/github-iterators.go) 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.

## Related how-tos

- [Loop over every page of a REST collection](/howto/loop-over-every-page-of-a-collection)

- [Expose paged results as an async iterator in TypeScript](/howto/paged-results-as-an-async-iterator-in-typescript)

- [Paginate an API with Python generators](/howto/paginate-an-api-with-python-generators)

## 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.

[^1]: The [specification](https://go.dev/ref/spec#For_range) 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](https://go.dev/blog/range-functions), dated August 20, 2024, states what the iterator
does, more mildly: when `yield` returns false, no more values are needed.

[^2]: The [features reference](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md)
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.