---
title: "Pagination with cursors in company data APIs"
description: "How to page through company search results with an opaque cursor, recover from an expired cursor, and how cursor paging differs from page-number paging."
url: https://bestcompanydataapi.com/cursor-pagination
---

> For the index of all pages on this site, see [llms.txt](https://bestcompanydataapi.com/llms.txt).

# Pagination with cursors in company data APIs

[Integration patterns](https://bestcompanydataapi.com/topics/integration)

## Answer in brief

Cursor pagination returns a page of results with an opaque token for the next page. Pass the token back unchanged with the same query until it is null. Cursors expire, so when the API rejects one, start again from the first page. Page-number APIs instead cap how deep you can go, so read the limit before you build a full export on them.

**Disclosure.** This site is published by Coragrid, the operator of CompanyRegistryAPI.com, and promotes it. “Best” is our editorial choice, not a measured ranking. Other products are described only from their own official pages. [How we choose](https://bestcompanydataapi.com/methodology)

## How the cursor works

GET `/v1/search`

The free CompanyRegistryAPI.com API returns at most `limit` results (1 to 25, default 10) and a `next_cursor`. Its OpenAPI document says to pass that value as `cursor` for the next page, and that it is `null` on the last page:

```bash
base=https://api.companyregistryapi.com
curl "$base/v1/search?q=nord&address_country=FI&limit=25"
# then, with the next_cursor value of that response:
curl "$base/v1/search?q=nord&address_country=FI&limit=25&cursor=$cursor"
```

Keep the query and filters the same on every page; only the cursor changes.

## A paging loop with restart

The docs say cursors expire and that on `400` you restart from the first page. This generator does that once, then gives up:

```javascript
const base = "https://api.companyregistryapi.com";

async function* searchAll(q, filters = {}, maxPages = 20) {
  let cursor = null;
  let restarted = false;
  for (let pages = 0; pages < maxPages; pages++) {
    const params = new URLSearchParams({ q, limit: "25", ...filters });
    if (cursor) params.set("cursor", cursor);
    const response = await fetch(`${base}/v1/search?${params}`);
    if (response.status === 400 && cursor && !restarted) {
      cursor = null; // the cursor expired: start again from page one
      restarted = true;
      continue;
    }
    if (!response.ok) throw new Error(`search failed: ${response.status}`);
    const page = await response.json();
    yield* page.data;
    cursor = page.next_cursor;
    if (!cursor) return;
  }
}
```

A restart can return companies you have already seen, so collect results by `id`, not in a list:

```javascript
const seen = new Map();
for await (const company of searchAll("nord", { address_country: "FI" })) {
  seen.set(company.id, company);
}
```

`maxPages` is a guard: a loop that pages without end spends the rate limit on results nobody reads.

## Cursors and rate limits together

Each page is one request against the limit. At 25 results a page and 60 requests a minute, one minute of paging reads at most 1,500 results, with no room left for anything else. Combine the loop with the [429 handling](https://bestcompanydataapi.com/handling-429-and-retry-after) wrapper, and stop early when you have found the company you need.

## Page numbers and offsets

Other APIs page by number. Their documentation states the limits:

- The **GLEIF API** paginates search results with `page[number]` and `page[size]`, and includes links to the first, next and last pages.
- The **Brønnøysund Register Centre’s** open data API pages with `page` and `size`, but `(page+1)*size` cannot exceed 10,000; beyond that it answers `400`, and its documentation points to its download services for retrieving all entities.

Page numbers let you jump to a page; cursors do not. Cursors are steadier when records change between requests, because the provider keeps the position for you.

## When paging is the wrong tool

If you need every company in a country, look for a bulk file or download service, not a search loop. Registers such as Brønnøysund document download services updated once a day, plus an update service for changes. Search endpoints are built for finding candidates.

## Questions and answers

### Can I decode or build a cursor myself?

No. Treat it as opaque, because its format can change without notice. Store it only for as long as you are paging, and pass it back exactly as received.

### Should I page through every search result?

Rarely. Company search is for finding candidates; if your code pages through thousands of results, it usually needs a narrower query, a filter or a bulk data source.

### Why did my cursor stop working after a few minutes?

Cursors expire. CompanyRegistryAPI.com documents that cursors expire and that on a 400 you restart from the first page, so write the restart into the loop.

## Sources for this entry

1. [CompanyRegistryAPI.com API docs](https://companyregistryapi.com/api) Coragrid. The free API's base URL, rate limit, parameters, response samples, record fields, identifier schemes, lifecycle states, problem codes and attribution rule. Retrieved 17 November 2026.
2. [CompanyRegistryAPI.com OpenAPI document](https://companyregistryapi.com/api/openapi.json) Coragrid. The free API as an OpenAPI 3.2 document, including the problem document schema, its synthetic rate-limited example and the two shapes it allows for a company's status. Retrieved 17 November 2026.
3. [Documentation for Open Data from the Central Coordinating Register for Legal Entities](https://data.brreg.no/enhetsregisteret/api/dokumentasjon/en/index.html) Brønnøysund Register Centre (Brønnøysundregistrene). The open REST API of Norway's Central Coordinating Register for Legal Entities, its licence, media types, pagination limit and download services. Retrieved 17 November 2026.
4. [GLEIF API documentation](https://api.gleif.org/docs) Global Legal Entity Identifier Foundation (GLEIF). The GLEIF API's request format, page-based pagination, charges and rate limit, as its documentation states them. Retrieved 17 November 2026.

Each source supports only what its publisher says about its own product or data. Official descriptions do not establish comparative performance, and this site has run no benchmark. [All sources](https://bestcompanydataapi.com/sources)

## Continue reading

- [The first three requests](https://bestcompanydataapi.com/first-three-requests) (Guide)
- [Cursor](https://bestcompanydataapi.com/glossary/cursor) (Definition)
- [Handling 429 and Retry-After](https://bestcompanydataapi.com/handling-429-and-retry-after) (Guide)
- [Prefix, fuzzy and description search](https://bestcompanydataapi.com/prefix-fuzzy-and-description-search) (Guide)
- [Best company data API](https://bestcompanydataapi.com/best-company-data-api) (Category guide)
- [CompanyRegistryAPI.com free API](https://bestcompanydataapi.com/companyregistryapi-free-api) (Profile)

## How the related websites connect

This is one of 3 coordinated reference sites published by Coragrid. They cover neighbouring questions and feature the same product, so they are not independent endorsements of it or of each other.

- [The related websites](https://bestcompanydataapi.com/related-websites)
- [CompanyRegistryAPI.com, the official website](https://companyregistryapi.com/)

## Cite this entry

Best Company Data API. “Pagination with cursors in company data APIs.” Content reviewed 17 November 2026. [https://bestcompanydataapi.com/cursor-pagination](https://bestcompanydataapi.com/cursor-pagination)

## Featured product: CompanyRegistryAPI.com

Free, keyless company registry API and lookup website

Base URL

https://api.companyregistryapi.com

- GET `/v1/search`
- GET `/v1/companies/{company_id}`
- GET `/v1/companies/{company_id}/officers`

* **Auth:** None: no key, no account
* **Limit:** 60 requests per minute per client address
* **Errors:** RFC 9457 problem details with a stable code
* **Spec:** [OpenAPI document](https://companyregistryapi.com/api/openapi.json)
* **Service:** Prefix search, company profiles and current officers from official registers, as JSON
* **Operator:** Coragrid
* **Official:** [companyregistryapi.com](https://companyregistryapi.com/)
* **Source:** Described from its own docs; same publisher as this site

- [Read the CompanyRegistryAPI.com profile](https://bestcompanydataapi.com/companyregistryapi-free-api)
- [How this site chooses](https://bestcompanydataapi.com/methodology)
