HTTPX · Function

httpx.post

Sends a synchronous HTTP POST request and returns an httpx.Response. It supports multiple body encodings plus query parameters, headers, authentication, proxy, timeout, redirect, TLS, and environment settings.

How it works

httpx.post performs a synchronous HTTP POST and returns an httpx.Response. Supply request data through options such as content, data, files, or json; query parameters and request metadata use params, headers, and related arguments. The top-level helper also exposes redirect, TLS verification, proxy, timeout, and environment settings.

Syntax

httpx.post(url, *, content=None, data=None, files=None, json=None, params=None, headers=None, cookies=None, auth=None, proxy=None, follow_redirects=False, verify=True, timeout=Timeout(timeout=5.0), trust_env=True)

Parameters

Name	Type	Description
`url`	`URL \| str`	Request URL.
`content`	`RequestContent \| None`	Raw request-body content.
`data`	`RequestData \| None`	Form data.
`files`	`RequestFiles \| None`	Multipart upload files.
`json`	`Any \| None`	JSON-serializable request body.
`params`	`QueryParamTypes \| None`	Query-string parameters.
`headers`	`HeaderTypes \| None`	Request headers.
`cookies`	`CookieTypes \| None`	Cookies to send.
`auth`	`AuthTypes \| None`	Authentication configuration.
`proxy`	`ProxyTypes \| None`	Proxy configuration.
`follow_redirects`	`bool`	Whether to follow redirects.
`verify`	`VerifyTypes`	TLS verification setting.

Returns

An httpx.Response containing the server response.

Key points

The function creates and sends an HTTP POST request.
Request bodies can be supplied as raw content, form data, uploaded files, or JSON.
Query parameters and common request metadata can be provided directly.
The default request timeout is five seconds.

Common mistakes

Use content for raw text or binary bodies rather than using data for that purpose.
Redirects are not followed unless you explicitly enable them.
Environment-based proxy and certificate settings are trusted by default; disable this when required for isolated behavior.

Example: Send JSON with POST

import httpx

response = httpx.post(
    "https://httpbin.org/post",
    json={"name": "Ada"},
    timeout=5.0,
)
response.raise_for_status()
print(response.json()["json"])

Sends a JSON POST request, raises for an unsuccessful HTTP status, and prints the decoded JSON payload.

When to use it

Send JSON

Submit structured data to an HTTP endpoint.

Send form data

Submit HTML-form-compatible fields.

Upload files

Upload a document or other multipart payload.

Upload raw content

Send bytes or raw text with a chosen body representation.

Interview questions

QWhat does httpx.post do?

It is the synchronous top-level helper for sending a POST request. It returns a response object and accepts the same request options documented for httpx.request.

Follow-up: How would you send a request without blocking? Use AsyncClient.post(...) and await the call, because async request methods are awaitable.

QHow do the body arguments differ?

Use data for form fields, files for multipart uploads, json for JSON encoding, and content for raw text, bytes, or a byte iterator. The helper selects the corresponding request-body handling from the supplied argument.

Follow-up: What should an async streaming upload provide? An async bytes generator, passed as the content to an async client request.

QWhich operational defaults should callers know?

The signature includes params, headers, cookies, auth, proxy, follow_redirects, verify, timeout, and trust_env in addition to body arguments. The default timeout is five seconds, redirects are disabled by default, and environment settings are trusted by default.

Follow-up: How can environment configuration be bypassed? Pass trust_env=False to the top-level call.

httpx.request
httpx.get
httpx.put
httpx.patch
httpx.delete
httpx.AsyncClient.post

Source: Developer Interface - HTTPX. Checked 2026-10-15.