OpenAlex technical documentation
  • Overview
  • Quickstart tutorial
  • API Entities
    • Entities overview
    • 📄Works
      • Work object
        • Authorship object
        • Location object
      • Get a single work
      • Get lists of works
      • Filter works
      • Search works
      • Group works
      • Get N-grams
    • 👩Authors
      • Author object
      • Get a single author
      • Get lists of authors
      • Filter authors
      • Search authors
      • Group authors
      • Limitations
      • Author disambiguation
    • 📚Sources
      • Source object
      • Get a single source
      • Get lists of sources
      • Filter sources
      • Search sources
      • Group sources
    • 🏫Institutions
      • Institution object
      • Get a single institution
      • Get lists of institutions
      • Filter institutions
      • Search institutions
      • Group institutions
    • 💡Topics
      • Topic object
      • Get a single topic
      • Get lists of topics
      • Filter topics
      • Search topics
      • Group topics
    • 🗝️Keywords
    • 🏢Publishers
      • Publisher object
      • Get a single publisher
      • Get lists of publishers
      • Filter publishers
      • Search publishers
      • Group publishers
    • 💰Funders
      • Funder object
      • Get a single funder
      • Get lists of funders
      • Filter funders
      • Search funders
      • Group funders
    • 🌎Geo
      • Continents
      • Regions
    • Concepts
      • Concept object
      • Get a single concept
      • Get lists of concepts
      • Filter concepts
      • Search concepts
      • Group concepts
    • Aboutness endpoint (/text)
  • How to use the API
    • API Overview
    • Get single entities
      • Random result
      • Select fields
    • Get lists of entities
      • Paging
      • Filter entity lists
      • Search entities
      • Sort entity lists
      • Select fields
      • Sample entity lists
      • Autocomplete entities
    • Get groups of entities
    • Rate limits and authentication
  • Download all data
    • OpenAlex snapshot
    • Snapshot data format
    • Download to your machine
    • Upload to your database
      • Load to a data warehouse
      • Load to a relational database
        • Postgres schema diagram
  • Additional Help
    • Tutorials
    • Report bugs
    • FAQ
Powered by GitBook
On this page
  • Basic paging
  • Cursor paging
Export as PDF
  1. How to use the API
  2. Get lists of entities

Paging

PreviousGet lists of entitiesNextFilter entity lists

Last updated 10 months ago

You can see executable examples of paging in

Basic paging

Use the page query parameter to control which page of results you want (eg page=1, page=2, etc). By default there are 25 results per page; you can use the per-page parameter to change that to any number between 1 and 200.

  • Get the 2nd page of a list:

  • Get 200 results on the second page:

Basic paging only works to get the first 10,000 results of any list. If you want to see more than 10,000 results, you'll need to use .

Cursor paging

Cursor paging is a bit more complicated than , but it allows you to access as many records as you like.

To use cursor paging, you request a cursor by adding the cursor=* parameter-value pair to your query.

  • Get a cursor in order to start cursor pagination:

The response to your query will include a next_cursor value in the response's meta object. Here's what it looks like:

{
  "meta": {
    "count": 8695857,
    "db_response_time_ms": 28,
    "page": null,
    "per_page": 100,
    "next_cursor": "IlsxNjA5MzcyODAwMDAwLCAnaHR0cHM6Ly9vcGVuYWxleC5vcmcvVzI0ODg0OTk3NjQnXSI="
  },
  "results" : [
    // the first page of results
  ]
}

To retrieve the next page of results, copy the meta.next_cursor value into the cursor field of your next request.

This second page of results will have a new value for meta.next_cursor. You'll use this new value the same way you did the first, and it'll give you the second page of results. To get all the results, keep repeating this process until meta.next_cursor is null and the results set is empty.

Don't use cursor paging to download the whole dataset.

  • It's bad for you because it will take many days to page through a long list like /works or /authors.

  • It's bad for us (and other users!) because it puts a massive load on our servers.

Get the next page of results using a cursor value:

Besides using cursor paging to get entities, you can also use it in .

Instead, download everything at once, using the . It's free, easy, fast, and you get all the results in same format you'd get from the API.

https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=IlsxNjA5MzcyODAwMDAwLCAnaHR0cHM6Ly9vcGVuYWxleC5vcmcvVzI0ODg0OTk3NjQnXSI=
group_by queries
OpenAlex snapshot
this user-contributed Jupyter notebook!
https://api.openalex.org/works?page=2
https://api.openalex.org/works?page=2&per-page=200
https://api.openalex.org/works?filter=publication_year:2020&per-page=100&cursor=*
cursor paging
basic paging