Pagination

This setting is available in the Response Field Mapping view. Open Import Settings → Pagination.

APIs often return a large number of records, too many to send all at once. To avoid this, many APIs split the data into pages. This technique is called pagination.

Instead of giving you everything in a single response, the API returns a portion (for example, 100 records), along with either a link to the next page of data or a special cursor value. You use these to request more results until all the data is retrieved.

How Note API Connector Handles Pagination

Note API Connector supports two common pagination types:

• Next URL Pagination — follow the link provided by the API to the next page.
• Cursor Pagination — use a cursor (like a bookmark) provided by the API to fetch the next page.

You can choose either method depending on what your API uses.

Next URL Pagination

Note API Connector can automatically follow the "next page" link provided by the API, fetch more data, and continue until all the pages are loaded, or until you've reached a page limit you define.

How to Set It Up

To enable pagination in Note API Connector:

1. In the Response View, open Import Settings tab and enable Pagination.
2. Choose "Next URL" as the pagination method.
3. Choose whether to:
   • ✅ Fetch all pages — Note API Connector will continue following the next URLs until there are no more pages.
   • 🔢 Fetch a limited number of pages — Stop after the number of pages you specify.
4. In the Next URL Path field, specify where the next page URL is located in your API response.

How to Find the Next URL Path

To help you find the correct path:

1️⃣ On the right side, you'll see a tree view of your API response.
2️⃣ Find the field that contains the "next page" URL (e.g., pagination.next, meta.next, or links.next_url).
3️⃣ Click the copy icon to copy the path.
4️⃣ Paste it into the Next URL Path field in the pagination settings.

✅ Once pasted, Note API Connector will validate the path. If the path is correct, you'll see a green checkmark and a message confirming it's a valid path.

Advanced: Using JMES Path Format

The Next URL Path field also supports JMES Path expressions for more complex scenarios. For example, if you need to extract a URL from a nested array or apply conditional logic, you can use JMES syntax like data[0].links.next or paging.next.link.

Examples of Next URL Paths

tip

Even though APIs may look different, the logic is the same: look for the value that contains a URL to the next page.

---

Example 1: If the API response looks like this:

{
  "results": [...],
  "pagination": {
    "next": "https://api.example.com/data?page=2"
  }
}

The Next URL Path would be: pagination.next

---

Example 2: If the API response looks like this:

{
  "data": [...],
  "meta": {
    "next": "https://api.myapi.com/data?offset=20"
  }
}

The Next URL Path would be: meta.next

---

Example 3: If the API response looks like this:

{
  "items": [...],
  "links": {
    "self": "https://...",
    "next_url": "https://api.anotherapi.com/page/3"
  }
}

The Next URL Path would be: links.next_url

---

Example 4: Some APIs return null or an empty string when there are no more pages to fetch:

{
  "data": [...],
  "nextPage": null
}

or

{
  "data": [...],
  "nextPage": ""
}

The Next URL Path would be: nextPage

Note: This usually means you're already on the last (or only) page. Pagination stops when the value is null, empty, or missing.

Cursor Pagination

Some APIs don’t give you a link to the next page. Instead, they use something called a cursor.

Think of a cursor like a bookmark. When you fetch data, the API gives you a small “bookmark” (often called next_cursor or similar). You send that bookmark back in your next request, and the API uses it to give you the following set of results. You repeat this process until there are no more bookmarks left.

How to Set It Up

1. In the Response View, open Import Settings tab and enable Pagination.
2. Choose "Cursor" as the pagination method.
3. Choose whether to:
   • ✅ Fetch all pages — keep going until there are no more results.
   • 🔢 Fetch a limited number of pages — stop after the number you specify.
4. In the Cursor Path field, enter where the cursor value appears in your API response (e.g., data.next_cursor).
5. In the Cursor Parameter Name field, enter the name of the parameter the API expects when you send the cursor back (e.g., cursor).

How to Find the Cursor Path and Parameter

• Use the API Response Tree View on the right to locate the field with the cursor value (it might be called next_cursor, endCursor, or something similar).
• Click to copy the path and paste it into the Cursor Path field.
• Then check your API docs (or the response) to see the name of the parameter that carries the cursor when requesting the next page (for example, "cursor": "abc123"). Enter that into the Cursor Parameter Name field.

Advanced: Using JMES Path Format

The Cursor Path field also supports JMES Path expressions for extracting cursor values from complex response structures. For example, you can use data[-1].id to get the ID of the last item in an array, or results[*].cursor | [0] for conditional cursor extraction.

Example

If the API response looks like this:

{
  "data": [...],
  "paging": {
    "next_cursor": "abc123"
  }
}

• Cursor Path: paging.next_cursor
• Cursor Parameter Name: cursor

✅ With this setup, Note API Connector will keep following the cursor until all the data is imported (or until you stop it after a set number of pages).

Real-World Pagination Examples

For complete step-by-step pagination setups in popular APIs, see these tutorials:

• Stripe Cursor Pagination - Excellent example using cursor pagination with JMES expressions (data[-1].id) and starting_after parameter
• HubSpot Next URL Pagination - Next URL pagination using paging.next.link
• Pipedrive Cursor Pagination - Cursor pagination for large datasets with next_cursor

Summary

• Pagination lets APIs return large datasets in smaller chunks.
• Note API Connector supports:
  • Next URL Pagination — the API gives you a link to the next page.
  • Cursor Pagination — the API gives you a bookmark (cursor) to fetch the next page.
• In both cases, you can fetch all pages or stop after a set number of pages.
• Use the API Response Tree View to quickly find and copy the correct path for your pagination method.

This allows you to import full datasets without writing any code, even if the API response is paginated across dozens or hundreds of pages.