First Steps

The simplest FastAPI pagination looks like this:

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)


class UserOut(BaseModel):
    name: str
    email: EmailStr


users: List[UserOut] = [
    UserOut(name="John Doe", email="john-doe@example.com"),
]


@app.get("/users")
def get_users() -> Page[UserOut]:
    return paginate(users)

Be careful

If you use an ORM/DB framework you need to use the paginate function that is specific to your framework. Otherwise, you will need to load all data into memory and then paginate it which is not good for performance.

You can find more information about integrations in Available Integrations section.

Step 1: import pagination components

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)


class UserOut(BaseModel):
    name: str
    email: EmailStr


users: List[UserOut] = [
    UserOut(name="John Doe", email="john-doe@example.com"),
]


@app.get("/users")
def get_users() -> Page[UserOut]:
    return paginate(users)

• Page - a class that represents a paginated data.
• paginate - a function that paginates data and returns a Page instance.
• add_pagination - a function that adds a pagination feature to the app.

Step 2: add pagination to app

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)


class UserOut(BaseModel):
    name: str
    email: EmailStr


users: List[UserOut] = [
    UserOut(name="John Doe", email="john-doe@example.com"),
]


@app.get("/users")
def get_users() -> Page[UserOut]:
    return paginate(users)

If you forget to add add_pagination to your app, pagination will not work.

add_pagination

add_pagination will affect only endpoints that have Page as a return type/response model.

Step 3: create a route

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)


class UserOut(BaseModel):
    name: str
    email: EmailStr


users: List[UserOut] = [
    UserOut(name="John Doe", email="john-doe@example.com"),
]


@app.get("/users")
def get_users() -> Page[UserOut]:
    return paginate(users)

The return type/response model is Page. It means that this endpoint can use the paginate function inside it.

Step 4: paginate the data

from typing import List

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

from fastapi_pagination import Page, add_pagination, paginate

app = FastAPI()
add_pagination(app)


class UserOut(BaseModel):
    name: str
    email: EmailStr


users: List[UserOut] = [
    UserOut(name="John Doe", email="john-doe@example.com"),
]


@app.get("/users")
def get_users() -> Page[UserOut]:
    return paginate(users)

paginate function will return Page instance with paginated data.

Step 5: Start the application and check OpenAPI docs

You will see that pagination parameters were added to the endpoint.