Skip to main content
Pagination classes determine how large result sets are split into individual pages of data.

​
BasePagination

Base class for all pagination classes. 
from rest_framework.pagination import BasePagination

​
Methods

​
paginate_queryset(queryset, request, view=None)

Paginate a queryset if required, either returning a page object, or None if pagination is not configured.
​
queryset
QuerySet
required
The queryset to paginate
​
request
Request
required
The request instance
​
view
APIView
The view instance (optional)

​
get_paginated_response(data)

Return a Response object containing paginated data.
​
data
list
required
The serialized data for the page

​
get_paginated_response_schema(schema)

Return the schema for paginated responses.
​
schema
dict
required
The schema for the results

​
PageNumberPagination

A simple page number based pagination style that accepts a single number page number in the request query parameters. 
from rest_framework.pagination import PageNumberPagination

class MyPagination(PageNumberPagination):
    page_size = 10
    page_size_query_param = 'page_size'
    max_page_size = 100

​
Attributes

​
page_size
int
Number of items per page. Defaults to None (pagination disabled)
​
django_paginator_class
class
The Django Paginator class to use. Default is django.core.paginator.Paginator
​
page_query_param
str
Query parameter name for the page number. Default is 'page'
​
page_size_query_param
str
Query parameter name for page size. Default is None (client cannot control page size)
​
max_page_size
int
Maximum allowable page size. Only relevant if page_size_query_param is set
​
last_page_strings
tuple
Values that can be used to request the final page. Default is ('last',)
​
template
str
Template name for rendering pagination controls. Default is 'rest_framework/pagination/numbers.html'

​
Response Format

{
    "count": 123,
    "next": "http://api.example.org/accounts/?page=4",
    "previous": "http://api.example.org/accounts/?page=2",
    "results": [
        // ...
    ]
}

​
Methods

​
get_page_number(request, paginator)

Get the page number from the request query parameters. Return the URL for the next page, or None if there is no next page. Return the URL for the previous page, or None if there is no previous page.

​
LimitOffsetPagination

A limit/offset based pagination style that mirrors the syntax used when looking up multiple database records. 
from rest_framework.pagination import LimitOffsetPagination

class MyPagination(LimitOffsetPagination):
    default_limit = 10
    max_limit = 100

​
Attributes

​
default_limit
int
Default number of items to return. Defaults to None (pagination disabled)
​
limit_query_param
str
Query parameter name for the limit. Default is 'limit'
​
offset_query_param
str
Query parameter name for the offset. Default is 'offset'
​
max_limit
int
Maximum allowable limit value. Default is None
​
template
str
Template name for rendering pagination controls. Default is 'rest_framework/pagination/numbers.html'

​
Response Format

{
    "count": 123,
    "next": "http://api.example.org/accounts/?limit=100&offset=200",
    "previous": "http://api.example.org/accounts/?limit=100&offset=0",
    "results": [
        // ...
    ]
}

​
Methods

​
get_limit(request)

Get the limit from the request query parameters.

​
get_offset(request)

Get the offset from the request query parameters.

​
get_count(queryset)

Determine the object count, supporting either querysets or regular lists.

​
CursorPagination

Cursor-based pagination ensures consistent results even when items are being inserted or deleted. It works by using an opaque cursor value that the client uses to navigate through the results. 
from rest_framework.pagination import CursorPagination

class MyPagination(CursorPagination):
    page_size = 10
    ordering = '-created'

​
Attributes

​
page_size
int
Number of items per page. Defaults to None (pagination disabled)
​
cursor_query_param
str
Query parameter name for the cursor. Default is 'cursor'
​
ordering
str | tuple
Field(s) to use for ordering. Default is '-created'. Must be an unchanging, unique or nearly-unique field
​
page_size_query_param
str
Query parameter name for page size. Default is None
​
max_page_size
int
Maximum allowable page size. Only relevant if page_size_query_param is set
​
offset_cutoff
int
Maximum offset value to guard against malicious queries. Default is 1000
​
template
str
Template name for rendering pagination controls. Default is 'rest_framework/pagination/previous_and_next.html'

​
Response Format

{
    "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D",
    "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
    "results": [
        // ...
    ]
}

​
Methods

​
get_ordering(request, queryset, view)

Return a tuple of strings that may be used in an order_by method.

​
decode_cursor(request)

Given a request with a cursor, return a Cursor instance.

​
encode_cursor(cursor)

Given a Cursor instance, return a URL with encoded cursor.

​
Example

from rest_framework.pagination import PageNumberPagination
from rest_framework.response import Response

class StandardResultsSetPagination(PageNumberPagination):
    page_size = 100
    page_size_query_param = 'page_size'
    max_page_size = 1000

class MyView(generics.ListAPIView):
    queryset = MyModel.objects.all()
    serializer_class = MySerializer
    pagination_class = StandardResultsSetPagination

Build docs developers (and LLMs) love

Get started for freeTalk to us