How to Validate Query Parameters in FastAPI

In FastAPI, you validate query parameters by declaring them as function parameters with type hints and optional validation constraints using Query from fastapi. This lets FastAPI automatically check types, required status, default values, and value limits for query inputs.

Syntax

To validate query parameters in FastAPI, use function parameters with type hints and the Query helper. This allows you to specify default values, mark parameters as required, and add constraints like minimum or maximum values.

• param: type = Query(default, ...) declares a query parameter.
• default sets a default value or ... to make it required.
• Constraints like min_length, max_length, gt (greater than), and lt (less than) validate input values.

python

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str = Query(..., min_length=3, max_length=50),
    limit: int = Query(10, gt=0, lt=100)
):
    return {"q": q, "limit": limit}

Example

This example shows a FastAPI endpoint that requires a query parameter q to be a string between 3 and 50 characters, and an optional limit integer between 1 and 99 with a default of 10. FastAPI automatically validates these and returns errors if invalid.

python

from fastapi import FastAPI, Query
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/search/")
async def search(
    q: str = Query(..., min_length=3, max_length=50),
    limit: int = Query(10, gt=0, lt=100)
):
    return {"query": q, "limit": limit}

client = TestClient(app)

# Valid request
response_valid = client.get("/search/?q=fastapi&limit=5")

# Invalid request: q too short
response_invalid = client.get("/search/?q=hi&limit=5")

Output

response_valid.json() == {'query': 'fastapi', 'limit': 5}
response_invalid.status_code == 422

Common Pitfalls

Common mistakes include:

• Not using Query for validation and relying only on type hints, which skips constraints like length or value limits.
• Setting default values incorrectly, causing parameters to be optional when they should be required.
• Using wrong constraint names or types, which FastAPI ignores silently.

Always use Query(...) to mark required parameters and add constraints explicitly.

python

from fastapi import FastAPI

app = FastAPI()

# Wrong: no Query, no constraints
@app.get("/wrong/")
async def wrong(q: str):
    return {"q": q}

# Right: with Query and constraints
from fastapi import Query

@app.get("/right/")
async def right(q: str = Query(..., min_length=3)):
    return {"q": q}

Quick Reference

Parameter	Description	Example
default	Default value or use ... to require	q: str = Query(...)
min_length	Minimum string length	q: str = Query(..., min_length=3)
max_length	Maximum string length	q: str = Query(..., max_length=50)
gt	Value must be greater than	limit: int = Query(10, gt=0)
lt	Value must be less than	limit: int = Query(10, lt=100)
regex	Regex pattern to match	q: str = Query(..., regex="^item")

Key Takeaways

Use Query with type hints to validate query parameters in FastAPI.

Set default or ... in Query to control if a parameter is optional or required.

Add constraints like min_length, max_length, gt, and lt for precise validation.

FastAPI automatically returns clear errors if validation fails.

Avoid skipping Query when you need validation beyond simple type checking.