Combine Paginated API Responses into One JSON Array

Combining paginated API responses means extracting data from multiple API pages and merging them into one JSON array.

Need to combine paginated API responses into one JSON array?

Most APIs return data in pages (page=1, page=2, or next_cursor). To actually use the data, you need to extract each page's results, merge them into a single list, and often flatten nested JSON before combining paginated API data.

This guide shows how to combine paginated API responses into one clean JSON array using a repeatable workflow.

Why paginated API responses are hard to use

• Data is split across multiple pages
• Each page wraps results differently
• You cannot directly export or analyze paginated data
• Duplicate records can appear across pages

To make the data usable, you must combine the pages into one dataset.

How to combine paginated API responses

To combine paginated API responses:

1. Collect all pages into one JSON array
2. Extract the result field (data, items, or results)
3. Flatten the arrays into one list
4. Deduplicate records if needed

The result is one clean JSON array ready for export or API use.

After combining, your data becomes a single JSON array that can be exported, analyzed, or sent to another API without pagination logic.

Combining paginated API responses usually turns multiple pages into an array of arrays, which must be flattened into a single list.

This process is also known as merging paginated API responses, flattening paginated data, or combining API result pages into one dataset.

Common use cases include exporting paginated customer records, combining paginated webhook batches, and preparing paginated analytics data for BI tools or CSV downloads. This workflow also helps when you need to merge paginated JSON, clean up API pagination JSON, or flatten paginated data.

Paste your paginated API JSON -> run the pipeline -> get a clean array instantly

How do I combine paginated API responses?

Combine paginated API responses by extracting each page's result array and flattening them into one list.

Common use cases

• Export paginated API data to CSV or Excel
• Combine paginated webhook responses
• Merge customer records from multiple API pages
• Prepare analytics datasets from paginated endpoints

What is API pagination?

Handling pagination in API data is the process of combining multiple API response pages where separate page results become one clean, reusable JSON array.

Most APIs return data in pages to keep responses small and predictable. Page-based APIs use ?page=1, ?page=2, and so on. Cursor-based APIs return a next_cursor token. Link-based APIs include a next URL that points to the following page. Each style still leaves the user with multiple JSON payloads that need to be combined before the data is useful.

Pagination formats

For more background on REST pagination patterns, see GitHub's guide to using pagination in the REST API.

How to combine paginated API responses (Quick steps)

You can combine paginated API responses online by pasting each page into the editor, picking the result array path, running Aggregate with flatten (concatenate arrays), and previewing the merged output.

1. Paste each API page into the editor as one JSON array
2. Select Shape with extract mode, scope it to each page (Target Paths: $[*]), and set Path to the result key (such as data, items, or results)
3. Add Aggregate and set operation to flatten (concatenate arrays)
4. Preview the merged JSON array
5. Export, download, or reuse the workflow

You can export and download the combined JSON for use in Excel, Google Sheets, BI tools, APIs, or downstream workflows.

Example (Before / After)

Before: a paginated customers API returns three pages, each wrapping the records under a data field with a next URL pointing to the following page.

[
  {
    "page": 1,
    "next": "/customers?page=2",
    "data": [
      { "id": "cus_001", "email": "maya@example.com" },
      { "id": "cus_002", "email": "liam@example.com" }
    ]
  },
  {
    "page": 2,
    "next": "/customers?page=3",
    "data": [
      { "id": "cus_003", "email": "ava@example.com" },
      { "id": "cus_004", "email": "noah@example.com" }
    ]
  },
  {
    "page": 3,
    "next": null,
    "data": [
      { "id": "cus_005", "email": "ella@example.com" },
      { "id": "cus_006", "email": "owen@example.com" }
    ]
  }
]

After: the merged JSON array contains every customer record across the three pages, with the page wrappers removed.

[
  { "id": "cus_001", "email": "maya@example.com" },
  { "id": "cus_002", "email": "liam@example.com" },
  { "id": "cus_003", "email": "ava@example.com" },
  { "id": "cus_004", "email": "noah@example.com" },
  { "id": "cus_005", "email": "ella@example.com" },
  { "id": "cus_006", "email": "owen@example.com" }
]

If you also need to clean API responses before merging paginated data or flatten nested JSON for paginated analytics, the same pipeline approach can help you prepare the data.

Common problems with paginated API data

API pagination gets messy because endpoints, wrappers, and page boundaries are rarely consistent across services or even across versions of the same service.

Common problems include:

• different response wrappers across APIs (data vs items vs results) that may need API response cleanup before merging paginated data
• missing or empty pages that break naive concatenation
• duplicate records when pages overlap or retries fire twice, especially when you need to compare JSON changes between runs
• nested arrays that need to be unwrapped before they can be flattened for analytics

Without a repeatable workflow, combining paginated API data often becomes one-off scripts, fragile spreadsheet imports, or copy-paste merges that are hard to audit.

Unlike simple converters or one-off scripts, this approach should account for inconsistent wrappers, missing pages, and repeatable output rules.

Step-by-step: merge paginated JSON arrays

To merge paginated API data, decide which path holds each page's records, extract that path from every page, then concatenate the resulting arrays into one flat list.

The Shape and Aggregate utilities can apply the same pipeline repeatedly once the method is clear.

You can copy this setup for the Shape step (extract mode, scoped per page):

{
  "mode": "extract",
  "targetPaths": ["$[*]"],
  "path": "data"
}

Then add the Aggregate step. You can copy this setup for Aggregate with flatten (concatenate arrays):

{
  "targetPaths": [],
  "operation": "flatten"
}

For this example, the workflow does:

1. Use Shape with extract mode (targetPaths: ["$[*]"], path: "data") to pull the data array out of each page object, leaving an array of arrays such as [[cus_001, cus_002], [cus_003, cus_004], [cus_005, cus_006]].
2. Run Aggregate with flatten (concatenate arrays) to join those page arrays end-to-end.
3. Return one flat array containing every customer record across the three pages.

Result

You end up with:

• id
• email
• a single flat array that can be exported, deduped, or sent to a downstream API
• a stable workflow that handles any number of pages

If the workflow keeps too much wrapper data, narrow the Shape extract path to the exact result key (e.g. data or items.records). Smaller pipelines are usually easier to review, explain, and reuse.

The pipeline or support material below shows the example input, aggregate config, and final flat output.

Merge paginated API responses

To merge paginated API responses, extract the repeated result field from every page and concatenate those records into one dataset. This is the same core workflow whether the pages use data, items, results, or a nested path such as items.records.

Merge paginated JSON arrays

When paginated API responses are combined, the data often becomes an array of arrays:

[[...], [...], [...]]

Flattening merges them into:

[...]

This is the core step in combining paginated API responses. Shape with extract mode produces the array of arrays by pulling the result path out of each page. Aggregate with flatten (concatenate arrays) merges the paginated JSON arrays into one list, which you can then convert to CSV or send to another API.

Flatten paginated API data

Flatten paginated API data when each page contains an array of records and the final output needs to be one list. Flattening removes the page boundaries so exports, dashboards, and downstream APIs can read the records as a single dataset.

Combine paginated API responses: code vs workflow

You can also handle pagination programmatically using scripts or APIs. A developer workflow usually fetches each page, parses the payload, extracts the result array, and appends it to a running list before writing the merged JSON.

Using code:

• requires loops, retries, and parsing
• is harder to review or reuse
• needs extra checks for missing pages, duplicate records, and inconsistent wrappers

Using a JSON pipeline:

• is visual and repeatable
• is easier to debug
• is reusable across APIs

For complex APIs, a reusable workflow is easier to maintain. Python and JavaScript scripts still work when one team owns the API client and the response shape is stable, but visual pipelines are usually better when several APIs return different wrappers or reviewers need to inspect the merge logic without reading code.

Use scripts when the cursor or next logic lives close to the request layer. Use a visual workflow when the merge step needs to be reviewed, reused, or rerun across APIs, then reuse the workflow through the OpenAPI reference.

Unlike basic online converters, a reusable workflow should let you preview changes, adjust the result path, and rerun the same logic later.

Combine paginated API responses in JavaScript

For simple API responses where every page stores records under data, JavaScript can merge the pages with flatMap:

const pages = [page1, page2, page3];
const combined = pages.flatMap((page) => page.data);

This works well for stable page shapes. If pages use different result fields, nested paths, retries, or duplicate records, a repeatable JSON workflow is easier to review and reuse.

Try it with your data

Paste your paginated API JSON, run the pipeline, and get a clean array instantly:

• Shape to extract the result array
• Aggregate to flatten the extracted arrays

The output is one clean JSON array you can reuse in an API, download, or convert to CSV for Excel, Google Sheets, BI tools, or reporting.

Limitations

Combining paginated API data can break down when the page structure changes or when the transform layer is asked to do work that belongs in the fetch layer.

Common limitations include:

• cursor-based pagination still needs fetching outside the transform — the workflow cannot follow next_cursor tokens on its own
• very large APIs may produce thousands of pages that are easier to stream than to paste at once
• incomplete or partially failed page fetches can leave gaps the merge step cannot recover
• very large JSON files may exceed the editor's preview limit and need chunked processing

For very large JSON files, consider streaming or chunked processing before running the full merge workflow.

For these cases, fetch and assemble the pages first, then use Shape and Aggregate to perform the final merge in one auditable step.

Next steps

Once the paginated responses are combined, you can clean API responses before merging paginated data, flatten nested JSON after pagination, export combined JSON to CSV, or compare JSON changes between repeated API pulls.

Best pagination handling tool

The best approach should support:

• nested JSON
• reusable pipelines
• previewable output
• clear error handling
• export or API-ready results

Forge Json is designed for these use cases. Use it when paginated API responses are nested, inconsistent, reused across teams, or need a repeatable workflow rather than a one-off script.

Related workflows

• clean API responses before merging paginated data
• flatten nested JSON before converting to CSV
• export combined JSON to CSV
• compare JSON changes across API pulls

Use the example panel below to open this sample input and run the Shape and Aggregate workflow directly in the editor.

FAQ

What is API pagination?

API pagination is the practice of returning data in pages instead of one large response, using page numbers, cursors, or next URLs. Each page contains a slice of the result set, and the consumer is expected to combine the pages before using the data.

How do I combine paginated API responses?

Paste the pages into the editor as one JSON array, run Shape with extract mode on the result path (such as data), then run Aggregate with flatten (concatenate arrays) to join the page arrays into a single flat list. The output is one clean JSON array that can be exported, deduped, or sent to a downstream API.

Can I merge cursor-based API data?

Yes — once the cursor pages have been fetched and collected into a single JSON array, the same Shape plus Aggregate workflow merges them. The cursor logic itself still needs to run outside the transform, since the workflow does not call the API to follow next_cursor tokens.

Should I dedupe paginated results?

Often yes, especially when pages overlap or retries can fire twice. After the merge step, follow up with a dedupe pass on a stable identifier such as id, or clean API responses before storage for broader normalization.