Inspect client information
An endpoint needs connection metadata such as the caller's host.
FastAPI · Class
Request
Request is FastAPI's raw HTTP request object, injected into path operations or dependencies through a type annotation. Use it to inspect request-level data directly when standard parameter declarations do not provide the needed access.
How it works
Request is the raw incoming HTTP request object that FastAPI injects when a path-operation parameter is annotated with Request. It exposes request metadata and underlying connection information without applying FastAPI's normal parameter validation, conversion, or OpenAPI documentation to values read directly from it.
Syntax
Request(scope, receive=empty_receive, send=empty_send)Parameters
| Name | Type | Description |
|---|---|---|
scope | Scope | ASGI scope containing request metadata. |
receive | Receive | ASGI receive callable; defaults to empty_receive. |
send | Send | ASGI send callable; defaults to empty_send. |
Returns
A Request instance representing the incoming HTTP request.
Key points
- Annotate a path-operation parameter or dependency with Request to receive the raw incoming request object.
- Request is intended for direct access when normal FastAPI parameter declarations are insufficient.
- The public import is
from fastapi import Request. - Request extends HTTPConnection, so it represents an HTTP connection with request-specific behavior.
- Choose HTTPConnection rather than Request when shared dependencies must support both HTTP and WebSocket protocols.
Common mistakes
- Values obtained through Request directly bypass FastAPI's validation and conversion, so validate application inputs yourself.
- Data read directly from the request is not automatically converted, validated, or included in generated OpenAPI documentation.
Example: Read request client information
from fastapi import FastAPI, Request
app = FastAPI()
@app.get("/client")
async def client_info(request: Request):
return {"client_host": request.client.host if request.client else None}Declares Request as a path-operation parameter and returns the client's host.
When to use it
Read the raw request
Application code must access raw request details not modeled as FastAPI parameters.
Share connection-aware dependencies
A dependency needs protocol-neutral access across HTTP and WebSocket connections.
Interview questions
QHow is Request injected into a FastAPI endpoint?
Annotate a path-operation or dependency parameter with Request, and FastAPI supplies the raw request object. It can then be used to inspect request data and metadata directly.
Follow-up: When should HTTPConnection be used instead? Use it when a dependency must work for both HTTP requests and WebSockets.
QHow can an endpoint obtain the client's host?
Request provides direct access to the incoming request, including connection metadata such as the client address. The documented example reads request.client.host and returns it.
Follow-up: What should code do if the client information is unavailable? Treat request.client as optional and handle a missing value rather than dereferencing it unconditionally.
QWhere does FastAPI's Request object come from?
FastAPI exposes Request directly as a convenience, while the object comes from Starlette underneath. This means its behavior follows the underlying Starlette request implementation.
Follow-up: What is a practical consequence of that layering? Consult Starlette's Request documentation for details not covered by FastAPI's reference page.
Related
HTTPConnectionWebSocketAPIRouteFastAPI