How does FastAPI turn a return value into JSON bytes?
When a path operation returns, FastAPI turns the value into bytes in three stages. First it validates the value against the response model. Then it converts the result into JSON-compatible Python objects. Finally the response class encodes those objects. Which stages run, and how often, depends on what you return and whether a response_model or return annotation is declared.
Without a response model, FastAPI passes the value to jsonable_encoder. This function walks the structure recursively, converting datetimes, UUIDs, enums, dataclasses and Pydantic models into plain dicts, lists, strings and numbers. Nothing is validated. Every node is still visited in Python.
With a response model, FastAPI first prepares the content. In many releases, a returned Pydantic model is dumped to a dict at this point. FastAPI then validates that content against the response model. A dict is validated field by field. An ORM object is read attribute by attribute, which requires from_attributes and can trigger lazy loads. The validated result is serialized back into JSON-compatible Python objects, applying aliases and include/exclude rules.
Encoding happens last. JSONResponse passes those objects to the standard library json.dumps, which walks the same tree again.
The redundancy is easy to miss. A model you already built can be dumped, re-validated into a new instance, and dumped again before json.dumps traverses it once more. Pydantic's core could have produced JSON bytes directly in one pass.
These internals have changed between FastAPI and Pydantic releases. Check the source and documentation for the versions you have installed.
+------------------------------------------+
| path operation returns a value |
| (dict, ORM object or Pydantic model) |
+------------------------------------------+
| |
| no response_model | response_model/annotation
v v
+------------------------------+ +----------------------------------+
| jsonable_encoder | | 1. prepare content |
| recursive walk in Python | | Pydantic model may be dumped |
| converts datetime, UUID, | | to a dict here (many releases) |
| enum, dataclass, models | +----------------------------------+
| NO validation | |
+------------------------------+ v
| +----------------------------------+
| | 2. validate vs response model |
| | dict: field by field |
| | ORM: attribute by attribute |
| | (from_attributes, lazy loads) |
| +----------------------------------+
| v
| +----------------------------------+
| | 3. serialize to JSON-compatible |
| | objects (aliases, incl/exclude) |
| +----------------------------------+
v v
+----------------------------------------------------------------------+
| JSONResponse: stdlib json.dumps walks the same tree again -> bytes |
| redundant path: dump -> re-validate -> dump -> json.dumps |
+----------------------------------------------------------------------+
FastAPI's response path. Without a response model, the value goes through jsonable_encoder only. With one, it is prepared, validated and serialized. Both paths end in json.dumps, so a returned model can be walked several times. Internals vary by FastAPI and Pydantic version.
Why is Pydantic v2 faster, and where does that speed disappear?
Pydantic v2 moved validation and serialization out of Python and into pydantic-core, a compiled Rust library. When you define a model, Pydantic builds a schema once, and the core uses it to check types, coerce values and write output without running Python bytecode for each field. A call like model_dump_json() can go from a model instance to JSON bytes entirely inside that core. This is the main reason teams upgrade for throughput.
That speed only applies while the work stays in Rust. It disappears in three common ways:
- Returning objects that are not already models. If an endpoint returns ORM rows, dataclasses or plain dicts, the response model has to validate them first. With
from_attributes, that means reading attributes from Python objects one at a time. If the handler already built a model instance and the framework validates it again against the response model, you pay for validation twice. - Dumping to Python, then encoding separately.
model_dump()creates a tree of dicts, lists and strings in Python. A second encoder then walks that tree to produce bytes. Each step allocates Python objects that are thrown away right after. - Custom serializers and computed fields. A
field_serializer,model_serializerorcomputed_fieldis a Python function. The core has to call back into Python for every object, so a list of 10,000 items means 10,000 interpreter calls.
The key point is that duplicate work usually costs more than the JSON encoder does. Changing the encoder will not help much if each object is validated twice and converted into Python objects before it is serialized.
How do you find out whether validation, conversion or encoding is the bottleneck?
Before you remove any of that duplicate work, confirm where the time actually goes. A slow endpoint can spend its time in validation, in converting models to Python dicts and lists, in JSON encoding, or outside serialization entirely. Each one needs a different fix.
Profile the real endpoint first
Run the service under realistic load and attach py-spy to the worker process with py-spy record --pid <PID>. Py-spy samples the running interpreter without code changes, so you see production-like behavior rather than a test harness. Look at how much of the flame graph sits under FastAPI's response serialization and Pydantic calls. Compare that with database drivers, ORM loading and awaiting I/O. Much of Pydantic's work runs in compiled code. Without native sampling, that time is attributed to the Python line that called into it, which is usually enough to tell which phase is hot.
Then isolate each phase
Once you know serialization matters, capture a few representative payloads: typical, large and worst-case. Time model_validate, model_dump and model_dump_json separately with timeit on those payloads. If model_dump plus the encoder costs far more than model_dump_json, the intermediate Python objects are the waste. If model_validate dominates, the problem is input or ORM conversion, not output.
Know when the numbers don't matter
A micro-benchmark that saves 2 ms per call is irrelevant when a query takes 80 ms or the client sits on a slow network (illustrative estimate). The same applies when payload size, not CPU, drives transfer time. Tuning pays off mainly for high-throughput, CPU-bound services that return large or deeply nested responses. If profiling shows serialization is a small share of request time, stop here and spend the effort elsewhere.
# bench_serialization.py: time each Pydantic v2 phase on its own.
# Replace make_payload() with payloads captured from the real endpoint where possible.
import json
import timeit
from pydantic import BaseModel
class Item(BaseModel):
sku: str
quantity: int
price: float
class Order(BaseModel):
id: int
customer: str
items: list[Item]
class OrderPage(BaseModel):
orders: list[Order]
def make_payload(n_orders: int, n_items: int) -> dict:
return {"orders": [
{"id": i, "customer": f"customer-{i}",
"items": [{"sku": f"SKU-{j}", "quantity": j % 5 + 1, "price": 9.99}
for j in range(n_items)]}
for i in range(n_orders)]}
PAYLOADS = {"typical": make_payload(20, 3), "large": make_payload(500, 10),
"worst": make_payload(5000, 20)}
for name, raw in PAYLOADS.items():
model = OrderPage.model_validate(raw)
cases = {
"model_validate": lambda: OrderPage.model_validate(raw), # input / ORM side
"model_dump": lambda: model.model_dump(), # build dicts and lists only
"model_dump+json.dumps": lambda: json.dumps(model.model_dump()), # two-step encode
"model_dump_json": lambda: model.model_dump_json(), # single-step encode
}
for label, fn in cases.items():
# Take the best of several repeats to reduce scheduler and GC noise.
best = min(timeit.repeat(fn, number=20, repeat=5)) / 20
print(f"{name:8} {label:22} {best * 1000:8.3f} ms/call")
A timeit script that measures model_validate, model_dump, model_dump followed by json.dumps, and model_dump_json separately on typical, large and worst-case payloads, so you can see which phase dominates before you change any code.
Implementing the fast paths without breaking the response contract
Start at the boundary between your data layer and the response. If the handler returns an ORM object and FastAPI validates it against response_model, every attribute is read, coerced and copied into a new model instance on each request. Building the response model yourself, for example with model_validate and from_attributes=True on the model config, makes that conversion explicit and happens once. It also lets you select only the columns the model needs.
Next, serialize with model_dump_json(). It runs in pydantic-core and writes the JSON string directly. model_dump() followed by a separate encoder first builds a Python dict, allocating an object for every field before any bytes are produced.
When the data is already trusted, wrap those bytes in a Response with media_type="application/json". FastAPI does not validate or re-serialize a returned Response, so this removes its second pass. FastAPI also cannot infer the schema from a Response, so keep response_model (or responses) on the route decorator. Declared that way, it documents the endpoint without running on the result, and the OpenAPI spec still matches what clients receive.
For collections, create TypeAdapter(list[Item]) once at module level and call its dump_json. Constructing an adapter builds a core schema, which costs far more than serializing a typical payload.
Use model_construct only for data that was validated upstream. It skips coercion and checks entirely. A string where an int belongs stays a string, and nested dicts are not converted into submodels. The resulting JSON can carry the wrong types without raising an error. At most you get a serialization warning, and that is easy to miss in production logs.
from types import SimpleNamespace
from fastapi import FastAPI, Response
from pydantic import BaseModel, ConfigDict, TypeAdapter
class Item(BaseModel):
model_config = ConfigDict(from_attributes=True) # read attributes off ORM rows
id: int
name: str
price_cents: int
# Build the core schema once at import time, never inside a handler.
ITEM_LIST = TypeAdapter(list[Item])
app = FastAPI()
def fetch_rows():
# Stand-in for an ORM query that selects only the columns Item needs.
return [SimpleNamespace(id=1, name="widget", price_cents=1999)]
# response_model stays on the decorator so OpenAPI documents the shape,
# but FastAPI does not validate or re-serialize a returned Response.
@app.get("/items", response_model=list[Item])
def list_items() -> Response:
items = ITEM_LIST.validate_python(fetch_rows(), from_attributes=True) # validate once
return Response(content=ITEM_LIST.dump_json(items), media_type="application/json")
@app.get("/items/{item_id}", response_model=Item)
def get_item(item_id: int) -> Response:
item = Item.model_validate(fetch_rows()[0], from_attributes=True)
# model_dump_json writes JSON in pydantic-core with no intermediate dict.
return Response(content=item.model_dump_json(), media_type="application/json")
# Pitfall: model_construct skips validation entirely.
# bad = Item.model_construct(id="42", name="widget", price_cents=1999)
# bad.model_dump_json() emits '"id":"42"' (a string, not an int) and at most
# logs a serialization warning. Use it only on data already validated upstream.
A FastAPI route that validates ORM rows once into Pydantic models, serializes them with a module-level TypeAdapter or model_dump_json into a prebuilt Response, keeps response_model on the decorator for OpenAPI, and shows how model_construct can silently emit wrong types.
Which model design choices make serialization slower?
Once the fast paths are in place, the remaining cost is mostly per object, and it comes from how the models are shaped. Pydantic's core does most of its work in Rust. Anything that sends it back into Python, or makes it inspect more than one candidate type, adds up across a list of thousands of items.
Deep nesting
Each nested model is a separate schema node. The serializer has to visit it, check its type and build its output. A response that wraps every scalar in its own small model does far more work than a flatter shape carrying the same data. If a submodel exists only to group two fields, consider inlining it.
Plain unions versus discriminated unions
With a plain A | B | C | D union, validation in the default smart mode may try several members before it settles on one. Serialization also has to work out which member the value belongs to. A discriminated union uses a literal tag field to pick the right member in a single step. That keeps the cost flat as you add variants, and it makes errors point at the correct branch.
Custom serializers
field_serializer and model_serializer functions run Python code for every instance. A wrap-mode model serializer on a list item model means one Python call per row. Keep these functions trivial, or move the transformation upstream into the query or a database view.
Computed fields
A computed_field runs on every dump. If it is expensive or triggers I/O, that cost repeats for every response and every item.
Strict mode
Strict mode and tighter types can speed up validation because Pydantic skips coercion attempts. The tradeoff is that coerced inputs, such as "42" sent for an integer field, now fail. Existing clients may depend on that coercion, so treat this as an API change rather than a tuning setting.
from datetime import datetime
from typing import Annotated, Literal, Union
from pydantic import (BaseModel, ConfigDict, Field, TypeAdapter,
ValidationError, computed_field, field_serializer)
class Card(BaseModel):
kind: Literal["card"]
last4: str
class Bank(BaseModel):
kind: Literal["bank"]
iban: str
# The "kind" tag selects the member directly instead of trying each one
Payment = Annotated[Union[Card, Bank], Field(discriminator="kind")]
class Order(BaseModel):
# Strict: no coercion, so a string "1" for an int field is rejected
model_config = ConfigDict(strict=True)
id: int
created_at: datetime
payment: Payment
subtotal_cents: int
tax_cents: int
# One Python call per Order on every dump. Pydantic already emits ISO 8601
# for datetimes in JSON, so a serializer like this adds cost and no value
@field_serializer("created_at")
def ser_created(self, v: datetime) -> str:
return v.isoformat()
# Recomputed on every dump: keep it cheap and never do I/O here
@computed_field
@property
def total_cents(self) -> int:
return self.subtotal_cents + self.tax_cents
orders = TypeAdapter(list[Order])
raw = b'[{"id": 1, "created_at": "2026-01-02T03:04:05Z", "payment": {"kind": "card", "last4": "4242"}, "subtotal_cents": 1000, "tax_cents": 80}]'
print(orders.dump_json(orders.validate_json(raw)))
try:
orders.validate_json(raw.replace(b'"id": 1', b'"id": "1"'))
except ValidationError as exc:
print(exc.errors()[0]["type"]) # int_type: a client sending "1" now breaks
An Order model that uses a discriminated union for payments and shows the per-row cost points: a redundant field_serializer, a computed_field that runs on every dump, and strict mode rejecting a coerced "1" that lax mode would have accepted.
When should you avoid bypassing response_model or skipping validation?
Each shortcut removes a guarantee that FastAPI and Pydantic were providing implicitly, so it is worth knowing exactly what you give up.
response_model is a filter as well as a validator. If a handler returns an ORM object or a dict that carries password_hash, an internal tenant ID or a debug field, the response model drops anything it does not declare. Return a JSONResponse or pre-encoded bytes and that filter is gone. The next field someone adds to the database row goes straight to clients. The OpenAPI schema also keeps describing the declared model while the real payload drifts away from it, and generated clients break against the docs.
model_construct trusts its input completely. When an upstream service renames a field or changes a type, nothing fails at construction time. Missing fields fall back to defaults, and wrong types pass through. The problem shows up later as a serialization warning, a malformed response or a client-side bug, far from its cause.
| Shortcut | Guarantee lost | Typical failure |
|---|---|---|
Dropping response_model |
Output filtering, type checks | Leaked internal or secret fields |
| Returning raw JSON | Schema-to-payload alignment | OpenAPI docs drift from real responses |
model_construct |
Input validation | Silent breakage when upstream shape changes |
Each shortcut also adds a second code path that needs its own tests, such as asserting the exact output keys and checking contracts against the schema. Reviewers also have to confirm by hand what the framework used to enforce. Use these shortcuts only on hot endpoints where profiling has shown a measured gain, and keep the validated path everywhere else.
What are the alternatives: orjson, streaming and pagination?
…version for the rest. When the response itself is too expensive, the fix is usually to change what you send rather than how you encode it.
orjson encodes plain dicts, lists and datetimes much faster than the standard json module. If your endpoint returns a JSONResponse built from plain dicts, switching the encoder can help. It gains little when Pydantic already produces the JSON bytes, because only the encoding step changes. Its output also differs from the standard library and from Pydantic. orjson.dumps returns bytes, not str. It rejects non-string dict keys unless you pass an option. It can format timezone offsets differently, for example +00:00 instead of Z. Tests that compare exact strings, and clients that parse strictly, can break.
Pagination limits the work done per request. Streaming (for example, NDJSON chunks through StreamingResponse) caps memory use and gets the first bytes to the client sooner. Streaming drops response_model filtering, so you must serialize each item through the model yourself.
| Option | Reduces CPU | Reduces bytes | Contract risk |
|---|---|---|---|
| orjson | Only for dict paths | No | Output format differences |
| Pagination | Yes | Yes | API shape change |
| Streaming | No (spreads it out) | No | Loses response_model |
Illustrative estimate. Assume a 200 KB payload, 8 ms of serialization per request, and 500 requests per second. That is 500 × 0.008 = 4 core-seconds per second, so about four cores spend all their time on serialization. The same traffic is also 100 MB/s, roughly 800 Mbit/s, on the network. Before you tune the encoder, check whether bandwidth and client parse time cost more than CPU. Pagination reduces both.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to pydantic v2 performance fastapi, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.