Query-Parameter

FastAPI Code Examples for Query Parameters

1. Basic Query Parameters and Defaults

If you assign a default value to a parameter, that parameter is not required. FastAPI will use the default value if the query parameter is not provided in the URL.

In the example below, skip defaults to 0 and limit defaults to 10.

Example URL	Resulting Function Values
http://127.0.0.1:8000/items/	skip=0, limit=10
http://127.0.0.1:8000/items/?skip=20	skip=20, limit=10

from fastapi import FastAPI

app = FastAPI()

# Database simulation
fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    # skip and limit are automatically interpreted as query parameters
    return fake_items_db[skip : skip + limit]

Source code supports this example.

2. Optional Query Parameters

To make a query parameter optional without assigning a specific default value, set its default to None. Using the modern Python syntax, this is defined as str | None = None.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None):
    # item_id is a path parameter. q is an optional query parameter.
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

Source code supports this example.

3. Boolean Type Conversion

FastAPI automatically converts incoming query parameter strings into the declared Python type. For boolean types (bool), FastAPI accepts several values as True, including 1, True, true, on, or yes (and their case variations).

In the code below, short is a boolean query parameter with a default value of False.

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: str, q: str | None = None, short: bool = False):
    item = {"item_id": item_id}
    if q:
        item.update({"q": q})

    # If short=True is provided in the URL (e.g., ?short=yes), the description is skipped.
    if not short:
        item.update(
            {"description": "This is an amazing item that has a long description"}
        )
    return item

Source code supports this example.

4. Required Query Parameters

To declare a query parameter as required, simply declare the parameter without assigning any default value. If a required query parameter is missing from the request, FastAPI will return an error stating that the field is required.

In this example, needy is a required query parameter.

Example URL	Result
http://127.0.0.1:8000/items/foo-item	Error: Field required for needy
http://127.0.0.1:8000/items/foo-item?needy=sooooneedy	Success

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_user_item(item_id: str, needy: str):
    # 'needy' is required because it has no default value
    item = {"item_id": item_id, "needy": needy}
    return item

Source code supports this example.

5. Mixing Path, Required, Default, and Optional Parameters

You can define multiple parameter types simultaneously, and FastAPI will automatically determine which are path parameters and which are query parameters based on the path definition string. The order of declaration in the function signature does not matter.

In the example below:

• item_id is a Path Parameter (str).
• needy is a Required Query Parameter (str).
• skip is a Query Parameter with a default value of 0 (int).
• limit is an Optional Query Parameter (int | None).

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_user_item(
    item_id: str,
    needy: str,
    skip: int = 0,
    limit: int | None = None
):
    item = {"item_id": item_id, "needy": needy, "skip": skip, "limit": limit}
    return item