How to Handle Paginated API Responses in TableCrafter

Updated July 2026 • 7 min read • By Fahad Murtaza

Most production APIs do not return all records in a single response. They paginate: 50 records per page, and you request additional pages with a page number or cursor parameter. TableCrafter's REST API source has native pagination support that maps API pagination to the table's built-in page controls, here is how to configure it. WordPress powers 43% of all websites globally (W3Techs, July 2026), and TableCrafter bridges the gap between the data you collect and the tables your users need to see, no custom PHP, no dashboard access required for viewers, and no per-row limits on the free tier. The free version on WordPress.org supports CSV, JSON, Google Sheets, and Excel. Pro adds Gravity Forms, Airtable, Notion, WooCommerce, REST APIs, inline cell editing, export to CSV/PDF, role-based column visibility, and auto-refresh. Every table embeds on any page with a [tablecrafter] shortcode or the native Gutenberg block. Bulk export features reduce administrative processing time by an average of 3.2 hours per week per team (HubSpot Operations Report, 2024).

Why API Pagination Matters for Table Display?

Without pagination handling, TableCrafter can only display the records in the first API response. For an API that returns 50 records per page and has 1,000 total records, a naive integration would show only 50 rows, and the user would have no indication that 950 records exist.

With pagination configured, TableCrafter fetches the correct page of results from the API as the user navigates between pages in the table. The total record count is communicated to the pagination UI so that the correct number of page buttons is displayed.

The configuration you set here applies to every visitor who loads a page containing this table, regardless of whether they are logged in. Role-specific overrides for columns and rows are a separate layer and do not replace these global display settings. Apply global settings first, then add role restrictions as needed for tables that serve multiple user types.

What Is the Two Pagination Patterns?

Offset-Based Pagination

The most common pattern. The API accepts parameters like page=1&per_page=50 or offset=0&limit=50. The page number (or offset) is the variable that changes with each page request. The API typically returns the total number of records in either the response body or a response header like X-Total-Count.

Examples of offset-based APIs:

• GitHub API: ?page=1&per_page=30, total in Link header
• WooCommerce REST API: ?page=1&per_page=10, total in X-WP-Total header
• WordPress REST API: ?page=1&per_page=10, total in X-WP-Total header
• Many custom APIs: ?page=1&limit=25, total in response body as total or count

Cursor-Based Pagination

Instead of a page number, cursor-based APIs return an opaque token in the response that represents the position of the last returned record. To fetch the next page, you pass this token back to the API. This pattern is more efficient for large datasets and avoids the "page drift" problem where inserted records cause items to appear on the wrong page.

Examples of cursor-based APIs:

• Stripe API: ?starting_after=ch_xxx&limit=25, cursor returned as has_more + last object id
• Twitter/X API v2: ?pagination_token=xxx, next token in response meta
• Airtable API: ?offset=xxx (despite the name, this is cursor-based, not offset-based)

How Do I Configure Offset-Based Pagination?

In the data source settings, open the Pagination section and select Offset-Based.

Page parameter settings

Configure how TableCrafter tells the API which page to fetch:

• Page Parameter Name: The query parameter name for the page number, commonly page, p, or pageNumber
• Page Size Parameter Name: The query parameter for the number of records per page, commonly per_page, limit, pageSize
• Page Size Value: How many records to request per page, must match or be fewer than the API's maximum allowed page size
• First Page Index: Whether the first page is 1 (most common) or 0 (some APIs use zero-based page numbers)

Total count settings

For the pagination UI to show accurate page numbers and a record count, TableCrafter needs to know the total number of records. Configure where to find this:

• Total From Response Body: Enter the JSON path to the total count field, for example total, meta.total, or pagination.total_records
• Total From Response Header: Enter the header name, for example X-Total-Count, X-WP-Total, or Total-Records

If neither is available (the API does not report a total), leave both blank. TableCrafter will operate in incremental mode: it will show Previous and Next buttons but cannot render a numbered page list or tell the user how many total records exist.

Example: WordPress REST API posts

The WordPress REST API endpoint /wp-json/wp/v2/posts is a perfect offset-based pagination example. Configuration:

• Endpoint URL: https://example.com/wp-json/wp/v2/posts
• Page Parameter Name: page
• Page Size Parameter Name: per_page
• Page Size Value: 10
• First Page Index: 1
• Total From Response Header: X-WP-Total

With this configuration, clicking page 3 in the table UI causes TableCrafter to fetch:

https://example.com/wp-json/wp/v2/posts?page=3&per_page=10

How Do I Configure Cursor-Based Pagination?

In the Pagination section, select Cursor-Based. The configuration differs significantly from offset-based:

• Cursor Parameter Name: The query parameter to pass the cursor value, for example starting_after, cursor, or pagination_token
• Cursor Path in Response: The JSON path to the next cursor value in the response, for example meta.next_cursor, next_page_token, or data.-1.id (the ID of the last object in the response array, used by Stripe)
• Has More Path in Response: Optional JSON path to a boolean field indicating whether more pages exist, for example has_more or meta.has_next_page

Current limitations of cursor-based pagination

Cursor-based pagination has a fundamental constraint: you cannot jump to an arbitrary page number because you need the cursor from the previous page to fetch the next one. TableCrafter's cursor pagination implementation reflects this:

• The pagination UI shows only Previous and Next buttons, no numbered page list
• There is no total record count display
• Jumping to page 7 directly is not possible, you must navigate forward sequentially
• TableCrafter caches cursors for the current session so that clicking Previous actually returns to the previous page rather than re-fetching page 1

How Do How Pagination Interacts with Sorting and Filtering Work?

When server-side pagination is configured, sorting and filtering requests are also passed to the API as query parameters, they are not applied client-side. This means the API must support sortable and filterable query parameters for those features to work correctly with pagination.

For example, if a user sorts the Name column in ascending order, TableCrafter will append &sort=name&order=asc (or whatever the API's parameter names are, as configured in the Sort Parameters section) to every paginated request.

If the API does not support server-side sorting or filtering, enable the Client-Side Processing option in the table display settings. With this enabled, TableCrafter fetches all pages from the API on initial load, concatenates the results, and handles sorting, filtering, and pagination entirely in the browser. This is only suitable for APIs with a manageable total record count, avoid it for APIs with more than a few thousand records.

How Does Debugging Pagination Issues Work?

Common problems and how to diagnose them:

• Table shows only the first page, Next button does nothing: The total count is not being read correctly. Check whether the API returns the total in the response body or a header, and verify the configured path or header name matches exactly (case-sensitive for headers).
• Page 2 returns the same results as page 1: The page parameter name is wrong. Use your browser's network tab to inspect the actual request URL and verify the page parameter is being appended.
• Cursor pagination goes back to page 1 on Previous: Session cursor caching may not be working. Clear your browser session and retry. If the problem persists, check whether the browser is blocking sessionStorage (private browsing modes on some browsers restrict it).
• Total shows as "Unknown": The API does not report a total and the Has More Path field is also blank. Set the Has More Path to whatever boolean field the API returns to indicate additional pages, even if you cannot display an exact total.