tiangolo.fastapi/docs/en/docs/tutorial/query-param-models.md

Query Parameter Models

If you have a group of query parameters that are related, you can create a Pydantic model to declare them.

This would allow you to re-use the model in multiple places and also to declare validations and metadata for all the parameters at once. 😎

/// note

This is supported since FastAPI version 0.115.0. 🤓

///

Query Parameters with a Pydantic Model

Declare the query parameters that you need in a Pydantic model, and then declare the parameter as Query:

//// tab | Python 3.10+

{!> ../../../docs_src/query_param_models/tutorial001_an_py310.py!}

////

//// tab | Python 3.9+

{!> ../../../docs_src/query_param_models/tutorial001_an_py39.py!}

////

//// tab | Python 3.8+

{!> ../../../docs_src/query_param_models/tutorial001_an.py!}

////

//// tab | Python 3.10+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial001_py310.py!}

////

//// tab | Python 3.9+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial001_py39.py!}

////

//// tab | Python 3.8+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial001_py310.py!}

////

FastAPI will extract the data for each field from the query parameters in the request and give you the Pydantic model you defined.

Check the Docs

You can see the query parameters in the docs UI at /docs:

Forbid Extra Query Parameters

In some special use cases (probably not very common), you might want to restrict the query parameters that you want to receive.

You can use Pydantic's model configuration to forbid any extra fields:

//// tab | Python 3.10+

{!> ../../../docs_src/query_param_models/tutorial002_an_py310.py!}

////

//// tab | Python 3.9+

{!> ../../../docs_src/query_param_models/tutorial002_an_py39.py!}

////

//// tab | Python 3.8+

{!> ../../../docs_src/query_param_models/tutorial002_an.py!}

////

//// tab | Python 3.10+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial002_py310.py!}

////

//// tab | Python 3.9+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial002_py39.py!}

////

//// tab | Python 3.8+ non-Annotated

/// tip

Prefer to use the Annotated version if possible.

///

{!> ../../../docs_src/query_param_models/tutorial002.py!}

////

If a client tries to send some extra data in the query parameters, they will receive an error response.

For example, if the client tries to send a tool query parameter with a value of plumbus, like:

https://example.com/items/?limit=10&tool=plumbus

They will receive an error response telling them that the query parameter tool is not allowed:

{
    "detail": [
        {
            "type": "extra_forbidden",
            "loc": ["query", "tool"],
            "msg": "Extra inputs are not permitted",
            "input": "plumbus"
        }
    ]
}

Summary

You can use Pydantic models to declare query parameters in FastAPI. 😎

/// tip

Spoiler alert: you can also use Pydantic models to declare cookies and headers, but you will read about that later in the tutorial. 🤫

///