Asynchronous API calls
Applications making concurrent outbound HTTP requests inside asyncio or another supported async environment.
HTTPX · Class
AsyncClient
HTTPX AsyncClient is an asynchronous, reusable HTTP client with connection pooling and shared configuration. Use it with await and manage its lifetime with an async context manager or aclose().
How it works
AsyncClient is HTTPX's asynchronous client for making HTTP requests with connection pooling and shared client configuration. Use it with async/await, either inside an async context manager or by explicitly calling aclose() when finished.
Syntax
httpx.AsyncClient(*, auth=None, params=None, headers=None, cookies=None, verify=True, cert=None, http1=True, http2=False, proxy=None, mounts=None, timeout=Timeout(timeout=5.0), follow_redirects=False, limits=Limits(max_connections=100, max_keepalive_connections=20, keepalive_expiry=5.0), max_redirects=20, event_hooks=None, base_url='', transport=None, trust_env=True, default_encoding='utf-8')Parameters
| Name | Type | Description |
|---|---|---|
auth | optional authentication class | Authentication class used for outgoing requests. |
params | optional string, dictionary, or sequence of two-tuples | Query parameters included in request URLs. |
headers | optional dictionary | Default HTTP headers. |
cookies | optional cookie mapping | Cookies persisted by the client. |
verify | boolean or SSL context | SSL verification configuration. |
cert | optional certificate configuration | Client certificate configuration. |
http1 | boolean | Whether HTTP/1.1 is enabled. |
http2 | boolean | Whether HTTP/2 is enabled. |
proxy | optional proxy configuration | Proxy configuration. |
mounts | optional mapping | Per-scheme or per-host transports. |
timeout | Timeout | Request timeout configuration. |
follow_redirects | boolean | Whether redirects are followed. |
Returns
An AsyncClient instance; its request methods return Response objects when awaited.
Key points
- AsyncClient is an asynchronous HTTP client with connection pooling and support for features including HTTP/2 and redirects.
- A single AsyncClient instance can be shared across concurrent tasks.
- Use the client's request-building and sending APIs when you need separate control over request creation and transmission.
- The send operation is asynchronous and returns a response after awaiting it.
- Use AsyncClient as an asynchronous context manager to scope its lifetime and clean up resources.
- The constructor supports a base URL, custom transport, environment trust setting, and default response encoding.
Common mistakes
- Streaming responses must be handled with AsyncClient.stream() as an asynchronous context block.
- Event hooks configured on AsyncClient must be asynchronous functions, not regular synchronous callables.
Example: Basic AsyncClient request
import asyncio
import httpx
async def main():
async with httpx.AsyncClient(base_url="https://example.org") as client:
response = await client.get("/")
response.raise_for_status()
print(response.status_code)
asyncio.run(main())Creates an asynchronous client, sends a request within its context, and closes the client automatically.
When to use it
Connection reuse
Services that make many requests and benefit from reusing pooled connections and shared defaults.
Custom transport integration
Tests or application integration where requests should be routed through a custom transport.
Interview questions
QWhat is AsyncClient and how is it used?
AsyncClient provides asynchronous HTTP requests and connection pooling. It can be shared between tasks, and request methods such as get() must be awaited.
Follow-up: How should its lifetime be managed? Use async with httpx.AsyncClient() for automatic cleanup, or call await client.aclose() explicitly.
QWhich kinds of configuration belong on AsyncClient?
The constructor accepts shared client configuration such as authentication, headers, cookies, timeout, proxy, redirects, limits, and a base URL. These settings apply to requests made through that client unless overridden.
Follow-up: What does base_url change? Relative request URLs are resolved against the configured base URL.
QDoes AsyncClient use HTTP/2 automatically?
AsyncClient supports HTTP/2 when constructed with http2=True, but HTTP/2 is not enabled by default. The actual protocol still depends on whether the server supports HTTP/2.
Follow-up: How can the negotiated protocol be checked? Inspect the response's http_version property.
Related
ClientRequestResponseLimitsTimeoutAsyncBaseTransportASGITransport