Pagination for articles and feeds

Pagination lets you request a window of an article collection without confusing the window size with the collection size. Use the same offset and limit parameters with GET /articles and GET /articles/feed, then use articlesCount to decide whether another page exists.

The pagination model

limit controls how many articles the response can contain. It is optional, has a default of 20, and must be at least 1. offset controls how many matching articles the API skips before it starts collecting the response. It is optional, defaults to 0, and cannot be negative.

The API orders article lists from most recent to oldest. The response therefore contains the next window in that order, while articlesCount continues to describe all matching articles. A page can contain fewer items than limit when you reach the end of the collection.

Choose the next page

Start at offset=0. After reading a page, advance the offset by the number of items you received, or by the requested limit when your client guarantees full pages. Stop when the offset reaches articlesCount, or when the response contains no articles. Do not use the length of the current page as the total count: a filtered collection can have more results than the current response contains.

For example, with two matching articles, limit=1 returns the newest article and articlesCount is 2. The request with limit=1&offset=1 returns the second article and still reports articlesCount as 2. The Hurl behavior test verifies both observations.

Request a page

The following request asks for the second page of articles authored by jake, with one article per page:

curl "https://api.realworld.show/api/articles?author=jake&limit=1&offset=1"

The response has the articles array and its independent total:

{
  "articles": [
    {
      "slug": "example-article",
      "title": "Example article"
    }
  ],
  "articlesCount": 2
}

Use the same parameters for the authenticated feed. The feed also requires the Authorization: Token <jwt> header:

curl "https://api.realworld.show/api/articles/feed?limit=20&offset=20" \
  -H "Authorization: Token <jwt>"

Validate pagination inputs

Treat offset and limit as integers before sending them. An offset below 0 violates the OpenAPI contract; a limit below 1 does the same. If the API rejects a value, parse the shared error envelope rather than assuming an empty page means there are no matches.

articlesCount is not a cursor and does not change the meaning of offset. It is the total number of articles that match the endpoint's filters at the time of the response. A later request can therefore observe a different count when articles are created or removed between pages.

Next steps

Use List and filter articles for the complete filter set, or read The followed-user feed when you need articles from followed profiles.