Query

API reference for the FastAPI Query parameter function

Query

Declare a query parameter for a path operation. Query parameters are the key-value pairs that appear after the ? in a URL.

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(max_length=50)] = None
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Signature

def Query(
    default: Any = Undefined,
    *,
    alias: str | None = None,
    title: str | None = None,
    description: str | None = None,
    gt: float | None = None,
    ge: float | None = None,
    lt: float | None = None,
    le: float | None = None,
    min_length: int | None = None,
    max_length: int | None = None,
    pattern: str | None = None,
    examples: list[Any] | None = None,
    deprecated: bool | str | None = None,
    include_in_schema: bool = True,
    json_schema_extra: dict[str, Any] | None = None,
) -> Any

Parameters

default · Any · default: "Undefined"

Default value if the parameter field is not set. If not provided, the query parameter will be required.

alias · str | None · default: "None"

An alternative name for the parameter field. This will be used to extract the data and for the generated OpenAPI. Particularly useful when you can’t use the name you want because it is a Python reserved keyword.

title · str | None · default: "None"

Human-readable title for the parameter.

description · str | None · default: "None"

Human-readable description for the parameter.

gt · float | None · default: "None"

Greater than validation. If set, the value must be greater than this. Only applicable to numbers.

ge · float | None · default: "None"

Greater than or equal validation. If set, the value must be greater than or equal to this. Only applicable to numbers.

lt · float | None · default: "None"

Less than validation. If set, the value must be less than this. Only applicable to numbers.

le · float | None · default: "None"

Less than or equal validation. If set, the value must be less than or equal to this. Only applicable to numbers.

min_length · int | None · default: "None"

Minimum length for strings.

max_length · int | None · default: "None"

Maximum length for strings.

pattern · str | None · default: "None"

RegEx pattern for strings.

discriminator · str | None · default: "None"

Parameter field name for discriminating the type in a tagged union.

strict · bool | None · default: "None"

If True, strict validation is applied to the field.

multiple_of · float | None · default: "None"

Value must be a multiple of this. Only applicable to numbers.

allow_inf_nan · bool | None · default: "None"

Allow inf, -inf, nan. Only applicable to numbers.

max_digits · int | None · default: "None"

Maximum number of allowed digits for numbers.

decimal_places · int | None · default: "None"

Maximum number of decimal places allowed for numbers.

examples · list[Any] | None · default: "None"

Example values for this field.

deprecated · bool | str | None · default: "None"

Mark this parameter field as deprecated. It will affect the generated OpenAPI (visible at /docs).

include_in_schema · bool · default: "True"

Whether to include this parameter field in the generated OpenAPI.

json_schema_extra · dict[str, Any] | None · default: "None"

Any additional JSON schema data.

Examples

Optional Query Parameter

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: Annotated[str | None, Query()] = None):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

Required Query Parameter

@app.get("/items/")
async def read_items(q: Annotated[str, Query(min_length=3)]):
    return {"q": q}

A query parameter is required when there is no default value.

Query Parameter with Default Value

@app.get("/items/")
async def read_items(
    skip: Annotated[int, Query(ge=0)] = 0,
    limit: Annotated[int, Query(ge=1, le=100)] = 10
):
    return {"skip": skip, "limit": limit}

String Validations

@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(min_length=3, max_length=50)] = None
):
    return {"q": q}

Pattern Validation

@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(pattern="^fixedquery$")] = None
):
    return {"q": q}

Query Parameter with Alias

@app.get("/items/")
async def read_items(
    item_query: Annotated[str | None, Query(alias="item-query")] = None
):
    return {"item_query": item_query}

Use alias when the query parameter name in the URL needs to be different from the Python variable name (e.g., for kebab-case parameters).

Deprecating Parameters

@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(deprecated=True)] = None
):
    return {"q": q}

Exclude from OpenAPI

@app.get("/items/")
async def read_items(
    hidden: Annotated[str | None, Query(include_in_schema=False)] = None
):
    return {"hidden": hidden}

Setting include_in_schema=False hides the parameter from the auto-generated API documentation.

List Query Parameters

from typing import Annotated
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(q: Annotated[list[str] | None, Query()] = None):
    return {"q": q}

This allows multiple values for the same query parameter: /items/?q=foo&q=bar