Documentation Python quickstart Blog Free tools Enterprise solutions hello@quanticdata.ioLog in

Python requests POST: json= vs data=, files and headers, with what the server received

Python requests POST sent three ways through a residential proxy to a test server: json= arrives as application/json with page 1 as a number, data= arrives as form fields with page as the string 1, and files= arrives as multipart form data; the card notes that a 302 redirect turned the POST into a GET while a 307 kept it a POST.
Python requests POST sent three ways through a residential proxy to a test server: json= arrives as application/json with page 1 as a number, data= arrives as form fields with page as the string 1, and files= arrives as multipart form data; the card notes that a 302 redirect turned the POST into a GET while a 307 kept it a POST.

To send a POST request in Python, call requests.post(url, json=payload) for a JSON body, data=dict for HTML form fields, or files= to upload. requests sets the Content-Type for you in all three cases. Add headers= for tokens, a timeout, and r.raise_for_status() to turn HTTP errors into exceptions.

We ran every call below on 20 November 2026 with Python 3.12.10 and requests 2.34.2, through a QuanticData Residential Basic session in the US, against httpbin.org/post, a public test endpoint that answers with exactly what it received. So the comments show the server's side, not just ours.

POST JSON with json=

import requests

PROXY = "http://USER-type-residential-country-us-session-post01-lifetime-30:PASS@residentialboson.quanticdata.io:10000"
px = {"http": PROXY, "https": PROXY}

r = requests.post("https://httpbin.org/post", json={"query": "proxy", "page": 1},
                  proxies=px, timeout=30)
print(r.status_code, r.request.headers["Content-Type"])   # 200 application/json
print(r.json()["json"])                                   # {'page': 1, 'query': 'proxy'}

json= serialises the dictionary, sets Content-Type: application/json, and the server received page as the number 1. This is what almost every modern API expects. The response is JSON too; reading it is covered in parsing the JSON response.

json= vs data=: the difference the server sees

The same dictionary passed as data= goes out as an HTML form:

r = requests.post("https://httpbin.org/post", data={"query": "proxy", "page": 1},
                  proxies=px, timeout=30)
print(r.request.headers["Content-Type"])   # application/x-www-form-urlencoded
print(r.json()["form"], r.json()["json"])   # {'page': '1', 'query': 'proxy'} None

Two differences. The Content-Type is form encoding, and every value became a string: page arrived as '1', not 1. The server's JSON field came back None: an API that reads the JSON body would find nothing in it. A classic HTML form, on the other hand, expects exactly this.

You passContent-Type requests sendsServer received
json={"page": 1}application/jsonJSON, page as number 1
data={"page": 1}application/x-www-form-urlencodedForm fields, page as text "1"
data=json.dumps({...})noneThe raw text; parsing depends on the server
data=json.dumps({...}) + headers={"Content-Type": "application/json"}application/jsonJSON

The third row is the classic bug in older code: data=json.dumps(payload) sends no Content-Type at all. Our test server happened to parse it anyway, but many APIs will not. Use json=, or set the header yourself.

Upload a file with files=

with open("upload.txt", "rb") as f:
    r = requests.post("https://httpbin.org/post",
                      files={"file": ("upload.txt", f, "text/plain")},
                      data={"note": "x"}, proxies=px, timeout=30)
print(r.request.headers["Content-Type"][:30])   # multipart/form-data; boundary=
print(r.json()["files"], r.json()["form"])      # {'file': 'hello\n'} {'note': 'x'}

Open the file in binary mode. The tuple sets the file name and type the server sees, and data= next to files= adds ordinary form fields to the same multipart body. Leave the Content-Type header to requests for uploads: it wrote the multipart boundary into it, and the server needs that value to split the parts.

Headers, tokens and sessions

r = requests.post("https://httpbin.org/post", json={"a": 1},
                  headers={"Authorization": "Bearer TOKEN", "X-Trace": "cb15"},
                  proxies=px, timeout=30)
print({k: r.json()["headers"][k] for k in ("Authorization", "X-Trace")})
# {'Authorization': 'Bearer TOKEN', 'X-Trace': 'cb15'}

Both headers reached the server unchanged through the proxy. When you make several calls to one API, put the headers and the proxy on a requests.Session() once; it also reuses the connection and keeps cookies between calls, which a login followed by POSTs needs. Headers set on the Session go with every request it sends.

Query parameters next to a POST body

Some APIs want both: a version or key in the URL and the payload in the body. params= and json= work together:

r = requests.post("https://httpbin.org/post", params={"v": "2"},
                  json={"query": "proxy"}, proxies=px, timeout=30)
print(r.url)              # https://httpbin.org/post?v=2
print(r.json()["args"], r.json()["json"])   # {'v': '2'} {'query': 'proxy'}

The same arguments work for the other methods that carry a body: requests.put(url, json={"a": 1}) returned 200 and the server read {'a': 1}, and requests.patch to httpbin.org/patch did the same with {"b": 2}. Keep the parameters you would see in a browser address bar in params, and the data you are sending in the body.

Errors, timeouts and the redirect trap

  • HTTP errors do not raise by themselves. A 405 came back as a normal response; r.raise_for_status() raised 405 Client Error: Method Not Allowed.
  • Always pass a timeout. A POST that hangs blocks your script forever otherwise. Retrying a POST needs care, because a repeated POST may create a record twice; the patterns are in retries and timeouts.
  • Redirects can turn a POST into a GET. We posted to an endpoint that answered 302: requests followed it as a GET to /get, the JSON body was dropped, and only r.history showed the 302. With a 307 it stayed a POST and the server received the body. If your POST "works" but nothing is saved, print r.history and r.request.method.

POST through a proxy

A proxy carries a POST like any other request: the body and headers above reached the server unchanged, and the server saw the proxy's US address instead of ours. A sequence of calls that belongs together (log in, then post) should use one session, with the session ID in the username, as we did here. Keep the pace of submissions modest, and send each form only once unless the site asks you to retry. Setup details: how to use a proxy with Python requests. QuanticData residential proxies and mobile proxies take the country and session in the username, and the Residential Basic free trial lets you test your POSTs before you buy. For the lower-level client underneath requests, see urllib3 vs requests.

Sources & further reading

FAQ

Quick answers on python requests post json.

Something else? Ask us

How do I send a POST request with JSON in Python?

Use requests.post(url, json=payload, timeout=30). requests serialises the dictionary and sets Content-Type: application/json; in our test the server received page as the number 1.

What is the difference between data and json in requests.post?

json= sends a JSON body with an application/json header. data= with a dictionary sends form fields, application/x-www-form-urlencoded, and every value arrives as text.

How do I send form data with Python requests?

Pass a dictionary to data=: requests.post(url, data={"q": "proxy"}). For file uploads with fields, combine files= and data=, which sends multipart/form-data.

How do I add headers to a POST request?

Pass headers={"Authorization": "Bearer TOKEN"} to requests.post, or set them once on a Session. Do not set Content-Type yourself when using json= or files=; requests does it.

Why did my POST become a GET?

The server answered with a redirect, and the follow-up request was a GET without the body. In our test a 302 led to a GET and a 307 kept the POST. Check r.history, or post to the final URL.

Proxies for requests.post and Session

Residential and mobile proxies with country and session settings in the username, ready for requests.post and Session.

Collectors with Python examples

Related reading