Pagination
Nexla API listing endpoints support paginated queries to limit the number of response objects and select which results to return. Pagination is especially useful for metrics, notifications, and other monitoring events when fetching every result in one call would be inefficient. The page-size parameter and pagination metadata depend on the endpoint.
These paginated queries are also a good way to use Nexla API monitoring events as a source of data in Nexla.
Resource Listing Pagination
Resource listing endpoints, such as /data_sources, and the /notifications endpoint use page and per_page. For example, /data_sources?page=2&per_page=10 fetches sources 11 to 20 in the default order. These pagination parameters work with the filtering parameters supported by the endpoint.
Responses to paginated queries contain a response header named Link which has a link to Previous and Next page of response. Note that absence of Previous signifies the response is the first page of data (i.e. no previous page available). Similarly, absence of Next signifies the response is the last page of data (i.e. no more pages available).
For example, the request below fetches error notifications 11 to 20 for source ID 6889 in the default order.
- Nexla API
GET /notifications?resource_type=SOURCE&resource_id=6889&level=ERROR&page=2&per_page=10
- Nexla API
Note: This is only a snippet of response headers:
link →< URL/notifications?resource_type=SOURCE&resource_id=6889&level=ERROR&page=1&per_page=10>; rel="Previous", <URL/notifications?resource_type=SOURCE&resource_id=6889&level=ERROR&page=3&per_page=10>; rel="Next"
X-Total-Count : 35
X-Current-Page : 2
X-Page-Count : 10
X-Total-Page-Count : 4
...
File Metrics Pagination
GET /data_sources/{source_id}/metrics/files supports pagination for file listings, including listings filtered to a single ingestion run.
| Parameter | Description | Default |
|---|---|---|
page | Page number, starting at 1. | 1 |
size | Number of file results per page. | 100 in the standard configuration |
Use positive integers for page and size. This endpoint currently has no explicit page-size cap. Start with size=100 for routine polling and specify the size explicitly to keep requests consistent across deployments. per_page, limit, and offset do not control pagination for this endpoint.
GET /data_sources/{source_id}/metrics/files?run_id={run_id}&page=1&size=100
Pagination metadata is returned in the response body:
| Field | Meaning |
|---|---|
metrics.meta.currentPage | Page number returned by this request. |
metrics.meta.totalCount | Total number of file results matching the request filters, across all pages. |
metrics.meta.pageCount | Total number of pages, calculated as ceil(totalCount / size). |
Keep run_id, size, and any other filters and sort options unchanged between pages. If currentPage is less than pageCount, request the next page by increasing page by 1. Stop when currentPage reaches pageCount, or when there are no matching results.
Listings with more results than the requested page size span multiple pages.
See Monitor a Data Source for supported sorting parameters, request examples, and a response example.