In FastAPI, how do you write an @app.middleware("http") function that adds a request-timing header, and which requests does it run for?
answer
- a decorator on the app object
- request plus call_next
- await first, then edit headers
- unmatched paths still pass through
- expose_headers for browser code
basics
~20 sDecorate an async function taking request and call_next with @app.middleware("http"), await call_next(request), then set a header such as X-Process-Time on the returned response. It wraps the whole router, so it also runs for 404s, and before any dependency.
solid answer
~30 sYou write `async def add_process_time_header(request: Request, call_next)` and decorate it with `@app.middleware("http")`. Inside, you take `time.perf_counter()`, `await call_next(request)` to run routing, dependencies and the path operation, then set `response.headers["X-Process-Time"]` and return the response. FastAPI registers it through `app.add_middleware(BaseHTTPMiddleware, dispatch=func)`, so it wraps the whole router: it sees requests no route matches (the 404 is produced inside `call_next`), 405s and 422s, and it runs before any dependency. It handles HTTP only, so WebSocket connections pass by it. If browser code on another origin must read the header, list it in `CORSMiddleware(expose_headers=[...])`.
code
python · 21 linesimport time
from collections.abc import Awaitable, Callable
from fastapi import FastAPI, Request, Response
app = FastAPI()
@app.middleware("http")
async def add_process_time_header(
request: Request, call_next: Callable[[Request], Awaitable[Response]]
) -> Response:
start = time.perf_counter()
response = await call_next(request)
response.headers["X-Process-Time"] = f"{time.perf_counter() - start:.6f}"
return response
@app.get("/items/{item_id}")
async def read_item(item_id: int) -> dict[str, int]:
return {"item_id": item_id}go deeper
Recall the shape: an async function with request and call_next, decorated with @app.middleware("http"), awaiting call_next and setting a header before returning the response.
Explain that the decorator registers BaseHTTPMiddleware around the router, so 404s, 405s and 422s pass through it, and dependencies run inside call_next.
Point out that call_next returns at header time, so streamed bodies escape the timing, and that WebSockets and CORS preflights may never reach this function.
Decide where request timing belongs for the team: a decorated function, a pure ASGI class, or the server and edge access logs, and keep one convention.
## What the decorator registers In FastAPI a **middleware** is code that runs around every request the application receives. The quickest way to write one is the decorator `@app.middleware("http")` placed on an `async def` function. The argument names the kind of traffic, and `"http"` is the only type the decorator supports. Under the hood the decorator is one line: FastAPI calls `self.add_middleware(BaseHTTPMiddleware, dispatch=func)`. `BaseHTTPMiddleware` is a Starlette class that turns the low-level ASGI interface into a request-and-response interface, and your function becomes its `dispatch` callable. Because it goes through `add_middleware`, the decorator and explicit `app.add_middleware(...)` calls share one stack. ## Writing the timing middleware The function receives two arguments: - **`request`**: a `fastapi.Request` (Starlette's `Request` re-exported) for the incoming call. - **`call_next`**: an async callable. `await call_next(request)` hands the request to the rest of the app (routing, dependencies, the path operation, exception handlers) and returns the `Response` they produced. Code before the `await` runs on the way in; code after it runs on the way out, where you can still change the response's headers before returning it: ```python @app.middleware("http") async def add_process_time_header(request: Request, call_next): start = time.perf_counter() response = await call_next(request) response.headers["X-Process-Time"] = f"{time.perf_counter() - start:.6f}" return response ``` The FastAPI docs use `time.perf_counter()` rather than `time.time()` because it is the more precise clock for measuring an interval. The function must return a response; returning the one from `call_next` is the normal case. ## Which requests it sees The decorated function wraps the router, not individual routes, so it runs for: 1. **Matched requests**, before any dependency or the path operation runs; both execute inside `call_next`. 2. **Unmatched paths**: the router produces the `404 {"detail": "Not Found"}` inside `call_next`, so the 404 still gets your header. 3. **Wrong methods and invalid input**: a 405 or a 422 validation error is also built inside `call_next`, so it passes back out through the middleware. It does **not** run for: - **WebSocket connections**: `BaseHTTPMiddleware` checks the ASGI scope type and passes anything other than `"http"` straight through. - **CORS preflight requests when `CORSMiddleware` was added after it**: the last-added middleware is outermost, and `CORSMiddleware` answers a preflight itself without calling inward. ## Passing values inward The middleware and the route share the same ASGI scope, so attributes set on `request.state` in the middleware are readable further in: - set `request.state.request_id = ...` before `await call_next(request)`; - read it in a dependency or path operation that declares `request: Request`; - copy it onto the response afterwards, for example as an `X-Request-ID` header. This is the usual way to hand a per-request value, such as a correlation id, to inner code without a global variable. The other direction is narrower: after `call_next` the middleware sees only the response's status, headers and body stream, never the path operation's Python return value. ## What the measured time means `call_next` returns as soon as the inner app has produced the response's status and headers. The body of a `StreamingResponse` is sent afterwards, while your middleware returns the wrapper. For a streamed answer the header therefore measures **time to the first byte of headers**, not the whole transfer. The returned object is a streaming wrapper with a `body_iterator` and no `.body` attribute, so reading the body means consuming and re-wrapping that iterator. ## Making the header visible to a browser A browser exposes only a few response headers to JavaScript on a cross-origin call. To let a frontend on another origin read `X-Process-Time`, add it to `CORSMiddleware(expose_headers=["X-Process-Time"])`. `allow_headers` is about request headers the browser may send, not response headers it may read. | Where the code sits | When it runs | |---|---| | Before `await call_next(request)` | on the way in, before routing and dependencies | | After `await call_next(request)` | on the way out, once headers are ready | | Not calling `call_next` at all | the app never sees the request | ## Common mistakes - Expecting it to apply to one router only: in FastAPI 0.143 middleware attaches to the application, not to an `APIRouter`. - Raising `HTTPException` from inside it: user middleware sits outside the layer that runs exception handlers, so the client gets a 500 instead. - Doing blocking work in it: it is an `async` function on the event loop, so a blocking call stalls every request in that process. - Forgetting `return response`: the function must return a response object, otherwise Starlette has nothing to send and the client gets a 500.
- Why does X-Process-Time look tiny for a slow StreamingResponse in FastAPI?`call_next` returns once the inner app has sent the status and headers; the streamed body is delivered after the middleware has already returned. The header measures time to the start of the response, not the full transfer. To time the whole exchange, write a pure ASGI middleware that wraps `send` and records the time when the final body message (no `more_body`) goes out.
- In a FastAPI app, does a timing middleware run before or after the path operation's dependencies?Before. Dependencies are solved by the route inside `call_next`, so the middleware's code before the `await` runs first and its code after the `await` runs once the route has produced a response. That is also why a dependency cannot see anything the middleware sets on the response, while the middleware can put values on `request.state` for dependencies to read.
- Says the middleware only runs for requests that match a route.
- Thinks @app.middleware("http") also wraps WebSocket connections.
- Expects call_next to return the path operation's raw return value.
- Lists the timing header in allow_headers to make the browser read it.
- Believes middleware runs after the path operation's dependencies.