Query params — ?key=value after the path

Function args that AREN'T path params become query params. Optional with defaults.

main.py v3.1

from fastapi import FastAPI

app = FastAPI()

fake_items = [{'id': i, 'name': f'item{i}'} for i in range(100)]

# Query params with defaults
@app.get('/items')
async def list_items(skip: int = 0, limit: int = 10):
    # /items                  -> skip=0, limit=10
    # /items?skip=20          -> skip=20, limit=10
    # /items?skip=20&limit=5  -> skip=20, limit=5
    return fake_items[skip:skip + limit]

# Mixed path + query
@app.get('/users/{user_id}/items')
async def user_items(user_id: int, skip: int = 0, limit: int = 10):
    return {'user_id': user_id, 'skip': skip, 'limit': limit}

# Optional query param (Optional[int] = None)
from typing import Optional
@app.get('/search')
async def search(q: Optional[str] = None, category: Optional[str] = None):
    if q is None:
        return {'message': 'Pass ?q=keyword to search'}
    return {'query': q, 'category': category}

# Boolean query param
@app.get('/flags')
async def flags(verbose: bool = False):
    return {'verbose': verbose}
# /flags            -> verbose=False
# /flags?verbose=true  -> verbose=True
# /flags?verbose=1     -> verbose=True (multiple truthy values)

API simulator click Simulate

Click "Simulate" to see what this FastAPI app does.

🧠 How it works

Function args that aren't path params are auto-treated as query params. Arg with default (limit: int = 10) — optional. Arg without default (q: str) — required. Optional[T] = None — explicitly optional, defaults to None. bool params accept: true/false, 1/0, yes/no, on/off (case-insensitive). Query params appear after ? in URL, separated by &: ?a=1&b=2&c=3. Great for pagination (skip/limit), filters (category), feature flags (verbose).

✏️ Try these changes

Change limit: int = 10 to limit: int = 5
→ fewer items per page
Add a new query param sort: str = 'asc'
→ /items?sort=desc
Change verbose: bool = False to verbose: bool = True
→ default flips
Add a required query param by removing the default: q: str
→ /items?q=... is required, returns 422 if missing

← Previous lab

Path parameters — {id} becomes a function arg

Next lab →

Pydantic request bodies — automatic validation