How to Use response_model_exclude in FastAPI for Response Filtering

In FastAPI, use the response_model_exclude parameter in your path operation decorator to exclude specific fields from the response model. Pass a set of field names to response_model_exclude to hide those fields in the returned JSON.

Syntax

The response_model_exclude parameter is used in FastAPI path operations to exclude fields from the response model. It accepts a set of strings representing the field names to exclude.

Example usage:

 @app.get("/items/{item_id}", response_model=Item, response_model_exclude={"field_to_exclude"})

Here, Item is the Pydantic model used for the response, and response_model_exclude tells FastAPI to omit the specified fields from the output.

python

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float

@app.get("/items/{item_id}", response_model=Item, response_model_exclude={"description"})
async def read_item(item_id: int):
    return {"name": "Book", "description": "A nice book", "price": 12.99}

Example

This example shows how to exclude the description field from the response JSON using response_model_exclude. The API returns only the name and price fields.

python

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float

@app.get("/items/{item_id}", response_model=Item, response_model_exclude={"description"})
async def read_item(item_id: int):
    return {"name": "Book", "description": "A nice book", "price": 12.99}

Output

{
  "name": "Book",
  "price": 12.99
}

Common Pitfalls

• Using a list instead of a set: response_model_exclude requires a set, not a list or tuple. Using a list will cause an error.
• Excluding non-existent fields: Trying to exclude fields not defined in the response model has no effect but can confuse debugging.
• Confusing response_model_exclude with exclude_unset: response_model_exclude explicitly excludes fields by name, while exclude_unset excludes fields not set in the model instance.

python

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str
    price: float

# Wrong: using list instead of set
@app.get("/items/{item_id}", response_model=Item, response_model_exclude={"description"})
async def read_item_wrong(item_id: int):
    return {"name": "Book", "description": "A nice book", "price": 12.99}

# Right: using set
@app.get("/items/{item_id}/correct", response_model=Item, response_model_exclude={"description"})
async def read_item_correct(item_id: int):
    return {"name": "Book", "description": "A nice book", "price": 12.99}

Quick Reference

response_model_exclude usage summary:

Parameter	Description	Type
response_model_exclude	Set of field names to exclude from the response model output	set[str]
response_model_include	Set of field names to include only in the response model output	set[str]
exclude_unset	Exclude fields not explicitly set in the model instance	bool
exclude_defaults	Exclude fields with default values	bool
exclude_none	Exclude fields with None values	bool

Key Takeaways

Use response_model_exclude with a set of field names to hide fields in FastAPI responses.

response_model_exclude only affects the output JSON, not the internal data or request body.

Always pass a set, not a list, to response_model_exclude to avoid errors.

response_model_exclude works with Pydantic models used as response_model in FastAPI.

Combine response_model_exclude with other exclude options for fine-grained control.