Cursor-based pagination for the REST API #414

New Issue

MrUnknownDE · 2026-04-05T16:30:44+02:00

MrUnknownDE commented

2026-04-05 16:30:44 +02:00

Originally created by @jeremystretch on 2/5/2026

NetBox version

v4.5.2

Feature type

New functionality

Proposed functionality

Implement cursor-based pagination for REST API, similar to what we did for the GraphQL API under #21110 in v4.5.2. This entails introducing a new start query parameter as an alternative to the offset parameter. This would be used in conjunction with the limit parameter` to paginate results, e.g.

GET /api/dcim/sites/?start=1234&limit=100

Unlike offset, which passes a relative position, the start parameter identifies a numeric primary key and returns all objects with a primary key equal to or greater than that value up to the specified limit. Note that objects must be ordered by primary key (rather than their native ordering by e.g. name) for effective pagination.

Note: This was proposed under FR #9599 but no workable implementation was identified at that time. It remains to be determined whether we can identify a feasible solution for the REST API.

Use case

The current pagination approach relies on a relative offset. This struggles with very large result sets, because the offset must be calculated by scanning the entire table up to the offset position. Employing an object's unique primary key as a cursor avoids this, as we can leverage simple numeric comparison to filter for all PKs greater than or equal to a given value. Combined with the existing limit capability, this affords very efficient pagination at the cost of a fixed (and not very meaningful) ordering.

Database changes

No response

External dependencies

No response

*Originally created by @jeremystretch on 2/5/2026* ### NetBox version v4.5.2 ### Feature type New functionality ### Proposed functionality Implement cursor-based pagination for REST API, similar to what we did for the GraphQL API under #21110 in v4.5.2. This entails introducing a new `start` query parameter as an alternative to the `offset` parameter. This would be used in conjunction with the `limit` parameter` to paginate results, e.g. `GET /api/dcim/sites/?start=1234&limit=100` Unlike `offset`, which passes a relative position, the `start` parameter identifies a numeric primary key and returns all objects with a primary key equal to or greater than that value up to the specified limit. Note that objects _must_ be ordered by primary key (rather than their native ordering by e.g. name) for effective pagination. Note: This was proposed under FR #9599 but no workable implementation was identified at that time. It remains to be determined whether we can identify a feasible solution for the REST API. ### Use case The current pagination approach relies on a relative offset. This struggles with very large result sets, because the offset must be calculated by scanning the entire table up to the offset position. Employing an object's unique primary key as a cursor avoids this, as we can leverage simple numeric comparison to filter for all PKs greater than or equal to a given value. Combined with the existing `limit` capability, this affords very efficient pagination at the cost of a fixed (and not very meaningful) ordering. ### Database changes _No response_ ### External dependencies _No response_

MrUnknownDE closed this issue

2026-04-05 16:30:44 +02:00

Sign in to join this conversation.

Branches Tags

main

21455-sql-indexes-audit

21357-register-model-actions

feature

20924-plugin-ui-components

21766-improve-test-coverage-for-sortable-table-columns

21157-export-template-public-models

21025-pre-render-config-contexts

21364-swagger

feature-ip-prefix-link

20911-dropdown-3

fix_module_substitution

21160-filterset

20911-dropdown-2

20044-elevation-stuck-lightmode

7604-filter-modifiers-v3

20660-script-load

19724-graphql

14884-script

19720-macaddress-interface-generic-relation

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

No Label complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium complexity: medium netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/netbox#414