Pagination

Relevant source files

The following files were used as context for generating this wiki page:

• packages/pagination/pagination.go
• paginationauto_test.go
• paginationmanual_test.go
• betafile_test.go
• betamessagebatch_test.go

Pagination in the Anthropic Go SDK provides a structured mechanism for retrieving large datasets from the API in manageable chunks. The system supports multiple pagination styles, including cursor-based (using IDs), token-based, and page-based approaches, allowing developers to choose between manual control over page requests or automated iteration through all available records.

The implementation is generic, enabling it to handle various data types (e.g., Message Batches or Files) while maintaining a consistent interface for the consumer. It integrates deeply with the SDK's request configuration to ensure that query parameters like limit, before_id, and after_id are correctly propagated across sequential requests.

Pagination Architectures

The SDK implements three primary styles of pagination, each defined by how the "next" set of data is identified and requested.

1. Cursor Pagination (Page[T])

This is the standard style used for resources like Message Batches and Files. It relies on first_id and last_id markers within the response to navigate forward or backward through the dataset.

• Logic: If the request contains a before_id, the next page is fetched using the FirstID. Otherwise, it uses the LastID as an after_id query parameter.
• Key Fields: Data, HasMore, FirstID, LastID.

Sources: packages/pagination/pagination.go:20-75, paginationmanual_test.go:29-33

2. Token Pagination (TokenPage[T])

This style uses a dedicated opaque token to identify the next page.

• Logic: The response contains a next_page string which is sent back to the API as a page_token query parameter.
• Key Fields: Data, HasMore, NextPage.

Sources: packages/pagination/pagination.go:119-158

3. Page Cursor (PageCursor[T])

Similar to token pagination but uses a different query parameter naming convention.

• Logic: The next_page value is applied to the page query parameter.
• Key Fields: Data, HasMore, NextPage.

Sources: packages/pagination/pagination.go:202-241

Automated Paging (AutoPager)

The SDK provides "AutoPager" types for each pagination style. These wrappers allow developers to iterate through every item in a collection without manually calling for the next page.

The diagram shows the internal logic of the Next() method within the AutoPager structs.
Sources: packages/pagination/pagination.go:88-103, paginationauto_test.go:29-33

AutoPager Component Comparison

Component	Style	Implementation Method
PageAutoPager[T]	Cursor (ID)	Uses after_id or before_id
TokenPageAutoPager[T]	Token	Uses page_token
PageCursorAutoPager[T]	Cursor (Page)	Uses page

Sources: packages/pagination/pagination.go:88-283

Data Structures and API Interactions

Core Data Models

The following table describes the fields found in the primary Page[T] struct, which is the most common pagination container in the SDK.

Field	Type	Description
Data	[]T	The slice of resource objects (e.g., Message Batches).
HasMore	bool	Indicates if more records exist beyond the current page.
FirstID	string	The ID of the first item in the current slice (used for backward paging).
LastID	string	The ID of the last item in the current slice (used for forward paging).

Sources: packages/pagination/pagination.go:20-36

Request Parameters

When listing resources that support pagination, the SDK accepts specific parameters to control the flow and size of the data.

• Limit: Controls the number of items returned per page.
• BeforeID: A cursor for use in backward pagination.
• AfterID: A cursor for use in forward pagination.

Sources: betafile_test.go:37-40, betamessagebatch_test.go:193-196

Sequence of Manual Pagination

Manual pagination requires the developer to explicitly request the next page from the current page object.

The sequence diagram illustrates the manual flow where the GetNextPage() method clones the original request configuration and applies new query parameters.
Sources: packages/pagination/pagination.go:49-75, paginationmanual_test.go:29-45

Usage Examples

Manual Iteration

In manual mode, the user iterates over the Data slice and calls GetNextPage() to retrieve the next set of results.

page, err := client.Beta.Messages.Batches.List(ctx, anthropic.BetaMessageBatchListParams{
    Limit: anthropic.Int(20),
})
// ... check error
for _, batch := range page.Data {
    // Process batch
}
nextPage, err := page.GetNextPage()

Sources: paginationmanual_test.go:34-45

Automatic Iteration

The ListAutoPaging methods return an iterator that handles network requests transparently.

iter := client.Beta.Messages.Batches.ListAutoPaging(ctx, params)
for iter.Next() {
    batch := iter.Current()
    // Process batch
}
if err := iter.Err(); err != nil {
    // Handle error
}

Sources: paginationauto_test.go:29-37

Conclusion

Pagination in the Anthropic Go SDK is a robust system designed to abstract the complexities of cursor management. By providing both manual GetNextPage() methods and automated Next() iterators across multiple pagination styles (ID-based, Token-based, and Page-based), the SDK ensures efficient data retrieval for resources such as message batches and files while maintaining type safety through Go generics.