Skip to content
NewsDataHub NewsDataHub API Docs

Pagination

The API uses cursor-based pagination for all list endpoints (/news, /top-news, /sources). Unlike offset-based pagination (which uses page numbers or skip/limit), cursor-based pagination maintains a stable position in the result set even as new data is added.

This prevents duplicate or missing results when paginating through a live dataset, and provides better performance on large result sets since the database doesn’t need to count or skip rows.

Response Structure

Section titled “Response Structure”

All paginated responses include these fields:

  • next_cursor (string or null) - Cursor for the next page of results, or null when you’ve reached the end
  • total_results (number) - Total count of results matching your query
  • per_page (number) - Number of results returned in this response
  • data (array) - Array of result objects

Controlling Page Size

Section titled “Controlling Page Size”

Use the per_page parameter to control how many results are returned per request. All tiers support up to 100 results per page. Default values vary by endpoint and tier:

  • /news: Free tier defaults to 10, paid tiers default to 50
  • /top-news: Paid tiers default to 50 (paid plans only)
  • /sources: Defaults to 20 (paid plans only)
  • /news/article_id/related: Defaults to 5 (paid plans only)

How It Works

Section titled “How It Works”
  1. Each response includes a next_cursor field when there are more results available.
  2. To get the next page of results, include this cursor value as the cursor query parameter in your next request.
  3. When there are no more results, next_cursor will be null.

Example Usage

Section titled “Example Usage”

Initial request:

Section titled “Initial request:”
https://api.newsdatahub.com/v1/news

Subsequent pages:

Section titled “Subsequent pages:”
https://api.newsdatahub.com/v1/news?cursor=MTI2OjIxOTg5Njc

End of results:

Section titled “End of results:”
{
  "next_cursor": null,
  "total_results": 150,
  "per_page": 50,
  "data": [...]
}

Error Handling

Section titled “Error Handling”

Invalid cursors are silently ignored and pagination restarts from the beginning. The API does not return an error for malformed cursors.

Best Practices

Section titled “Best Practices”

  • Don’t reuse cursors across different queries. Each cursor is tied to specific filter parameters. Changing filters invalidates the cursor and will cause pagination to restart.

  • Don’t store cursors for long-term use. Cursors are only valid for the current pagination session and may become invalid if the underlying data changes.

  • Handle null cursors gracefully. Always check if next_cursor is null before making the next request to avoid unnecessary API calls.

  • Use appropriate page sizes. Larger pages reduce the number of requests but increase response time. Balance based on your use case.

  • Pagination is forward-only. You cannot go backwards or jump to arbitrary pages. Design your application accordingly.

Learn More

Section titled “Learn More”

Deep dive into pagination best practices: