# Python requests POST: JSON, Form Data, Files

> Send POST requests in Python: json= for a JSON body, data= for form data, files= for uploads, custom headers, redirects and errors, run through a proxy.

[Home](https://quanticdata.io/) / [Blog](https://quanticdata.io/blog/) / Python requests POST: JSON, Form Data, Files

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

Guides · Nov 20, 2026 · 5 min read · By [Aldo Morese](https://quanticdata.io/about/), founder of QuanticData

![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.](https://quanticdata.io/blog/python-requests-post/hero.webp?v=20261120h)

On this page

- [POST JSON with json=](https://quanticdata.io/blog/python-requests-post/#post-json-with-json)
- [json= vs data=: the difference the server sees](https://quanticdata.io/blog/python-requests-post/#json-vs-data-the-difference-the-server-sees)
- [Upload a file with files=](https://quanticdata.io/blog/python-requests-post/#upload-a-file-with-files)
- [Headers, tokens and sessions](https://quanticdata.io/blog/python-requests-post/#headers-tokens-and-sessions)
- [Query parameters next to a POST body](https://quanticdata.io/blog/python-requests-post/#query-parameters-next-to-a-post-body)
- [Errors, timeouts and the redirect trap](https://quanticdata.io/blog/python-requests-post/#errors-timeouts-and-the-redirect-trap)
- [POST through a proxy](https://quanticdata.io/blog/python-requests-post/#post-through-a-proxy)

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.

**Run it on the free credit.** Every QuanticData account gets $2 of free API usage per month.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-lead&utm_content=python-requests-post) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

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=

```python
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](https://quanticdata.io/blog/parse-json-python/).

## 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 pass | Content-Type requests sends | Server received |
| --- | --- | --- |
| `json={"page": 1}` | application/json | JSON, page as number 1 |
| `data={"page": 1}` | application/x-www-form-urlencoded | Form fields, page as text "1" |
| `data=json.dumps({...})` | none | The raw text; parsing depends on the server |
| `data=json.dumps({...})` + `headers={"Content-Type": "application/json"}` | application/json | JSON |

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.

**Try it on your own targets.** Every QuanticData account gets $2 of free API usage per month.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-inline&utm_content=python-requests-post) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

## 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](https://quanticdata.io/blog/python-requests-retry/).
- **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](https://quanticdata.io/blog/how-to-use-a-proxy-with-python-requests/). QuanticData [residential proxies](https://quanticdata.io/residential-proxies/) and [mobile proxies](https://quanticdata.io/mobile-proxies/) take the country and session in the username, and the [Residential Basic free trial](https://quanticdata.io/residential-proxy-free-trial/) lets you test your POSTs before you buy. For the lower-level client underneath requests, see [urllib3 vs requests](https://quanticdata.io/blog/urllib3-vs-requests/).

### Sources & further reading

- [Requests: more complicated POST requests](https://requests.readthedocs.io/en/latest/user/quickstart/#more-complicated-post-requests)
- [Requests: POST a multipart-encoded file](https://requests.readthedocs.io/en/latest/user/quickstart/#post-a-multipart-encoded-file)
- [RFC 9110: 307 Temporary Redirect](https://www.rfc-editor.org/rfc/rfc9110#status.307)
- [MDN: POST](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)

## FAQ

Quick answers on python requests post json.

[Something else? Ask us](mailto:hello@quanticdata.io)

### 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.

[Start free — $2/month included](https://quanticdata.io/signup/?utm_source=blog&utm_medium=website&utm_campaign=blog-end&utm_content=python-requests-post) · [Explore Residential Proxies from $0.80/GB](https://quanticdata.io/residential-proxies/)

## Collectors with Python examples

- [Zalando Scraper API in Python](https://quanticdata.io/collectors/zalando-scraper-api/python/): Collector · Install, first call, async runs, output fields and errors of the Zalando Scraper collector, with Python examples.
- [eBay product data API in Python](https://quanticdata.io/collectors/ebay-product-api/python/): Collector · Install, first call, async runs, output fields and errors of the eBay product data collector, with Python examples.
- [Google Shopping scraper API in Python](https://quanticdata.io/collectors/google-shopping-api/python/): Collector · Install, first call, async runs, output fields and errors of the Google Shopping scraper collector, with Python examples.
- [Reverse image search API in Python](https://quanticdata.io/collectors/reverse-image-search-api/python/): Collector · Install, first call, async runs, output fields and errors of the Reverse image search collector, with Python examples.

## Related reading

- [Download Images From a Website With Python](https://quanticdata.io/blog/scrape-images-python/): Guides · Find the \<img> tags with Beautiful Soup, turn each src into a full URL with urljoin, download with requests in stream mode, check that the response is an image, and name files by their hash to skip duplicates. We ran the script on a practice shop through a residential proxy: 11 images in 2.7 s.
- [urllib3 vs requests: Speed and Bandwidth](https://quanticdata.io/blog/urllib3-vs-requests/): Guides · requests is built on urllib3 and adds sessions, JSON, exceptions on errors and compression by default. urllib3 alone was faster on a local server, the same through a proxy, and downloaded 9.5 times more bytes until we asked for compression. Measured, with the code.
- [Concurrency vs Parallelism, Measured in Python](https://quanticdata.io/blog/concurrency-vs-parallelism/): Guides · Concurrency is making progress on several tasks by switching between them; parallelism is running several at the same instant on different CPU cores. We timed both on a real scraping job in Python on 20 November 2026: threads cut 30 downloads from 10.3 s to 3.5 s, and only processes cut the parsing, from 3.5 s to 0.8 s.

---

Source: https://quanticdata.io/blog/python-requests-post/ · Site index for AI: https://quanticdata.io/llms.txt
