Python Requests: Query Parameters, Headers, and JSON Body
Learn how to send query parameters, custom headers, and JSON bodies with Python requests, including how to combine them in one request and avoid common API client mistakes.

Sending query parameters, custom headers, and a JSON body with the Python requests library is a common task when building API clients. This article explains how each part works and how to combine them in a single request.
When working with the Python requests library, you often need to send query parameters, custom headers, and a JSON body in one HTTP request. Understanding how these components combine is essential for building reliable API clients. This article covers the syntax and behavior of each part, then shows how they work together in realistic scenarios.
Constructing a Request with Query Parameters
The requests library accepts query parameters through the params keyword argument. This argument takes a dictionary or a list of tuples, and requests encodes it into the URL's query string automatically. For example:
import requests
params = {
"q": "python requests",
"page": 2,
"sort": "desc"
}
response = requests.get("https://api.example.com/search", params=params)
print(response.url)
# https://api.example.com/search?q=python+requests&page=2&sort=descThe library handles URL encoding for you. In the query string, spaces are typically encoded as +, and special characters are percent-encoded. If you need to pass a list of values for the same key, use a list in the dictionary:
params = {"tag": ["python", "http"]}
# https://api.example.com/search?tag=python&tag=httpThis is often more reliable than manually building the query string, especially when values contain reserved characters.
Setting Headers for Authentication and Content Type
Custom headers are passed via the headers argument. This is a plain dictionary mapping header names to values. Common use cases include authentication tokens, custom Accept types, and overriding the default User-Agent.
headers = {
"Authorization": "Bearer your-token-here",
"Accept": "application/json",
"User-Agent": "my-api-client/1.0"
}
response = requests.get("https://api.example.com/user", headers=headers)When you send a JSON body, the Content-Type header is set automatically by the json parameter. However, if you construct the body manually with data, you must set Content-Type yourself. For example:
import json
payload = {"name": "Alice", "role": "admin"}
headers = {"Content-Type": "application/json"}
response = requests.post("https://api.example.com/users", data=json.dumps(payload), headers=headers)Using json.dumps() and data gives you explicit control, but the json parameter is simpler and less error-prone.
Sending a JSON Body in POST Requests
The json parameter in requests.post() (and other methods) serializes a Python dictionary to a JSON string and sets the Content-Type header to application/json automatically. This is the recommended way to send JSON payloads.
payload = {
"title": "New Task",
"completed": False,
"tags": ["work", "urgent"]
}
response = requests.post("https://api.example.com/tasks", json=payload)The library converts the dictionary using json.dumps() internally, so you don't need to import the json module or manage the header. This also handles nested structures and Unicode correctly.
If you need to send a JSON body that is not a dictionary, such as a list or a scalar, you can still use json — it accepts any JSON-serializable object.
Combining Parameters, Headers, and JSON Body
A single request often needs all three: query parameters for filtering or pagination, headers for authentication or content negotiation, and a JSON body for the request data. The requests library allows you to pass all three arguments to the same call.
params = {"page": 1, "limit": 10}
headers = {
"Authorization": "Bearer token123",
"Accept": "application/json"
}
payload = {
"query": "python",
"filters": {"status": "active"}
}
response = requests.post(
"https://api.example.com/search",
params=params,
headers=headers,
json=payload
)When you do this, requests builds the URL with the query string, attaches the headers, and sends the JSON-encoded body. The order of keyword arguments does not matter, but keeping them grouped by purpose improves readability.
One subtlety: if a query parameter name matches a JSON body field, they are independent — the query parameter goes in the URL, the body field goes in the payload. This is exactly what most APIs expect.
Handling Response Content and Status Codes
After sending a request, you need to check whether it succeeded. The response object has a status_code attribute and a raise_for_status() method that raises an exception for 4xx and 5xx responses.
response = requests.post("https://api.example.com/tasks", json=payload)
if response.status_code == 201:
created_task = response.json()
print(created_task["id"])
else:
print(f"Request failed: {response.status_code}")The response.json() method parses the response body as JSON. If the response is not valid JSON, it raises a JSON decode exception such as requests.exceptions.JSONDecodeError. Always confirm the content type or status code before parsing.
For raw bytes, use response.content; for a decoded string, use response.text, which uses the encoding attribute. Both load the full response into memory, so for very large responses use stream=True and iterate with response.iter_content() or response.iter_lines().
Common Mistakes and How to Avoid Them
One frequent mistake is using data instead of json when sending a JSON payload. With data, a dictionary is form-encoded, and a string is sent as-is; to send JSON you must serialize it yourself and set the Content-Type header. This is why json is usually the better choice for JSON bodies.
Another issue is forgetting that query parameters are URL-encoded. If you build the URL manually and insert user input without encoding, you risk malformed URLs or injection vulnerabilities. Always use the params argument to let requests handle encoding.
Headers can also cause subtle bugs. For example, if you pass Content-Type in headers while also using json, requests uses your header and does not set the automatic application/json value. If the value is wrong, the server may not parse the body. Similarly, some APIs expect a specific Accept header to return JSON instead of XML.
Finally, the json parameter cannot serialize arbitrary objects; passing non-serializable values raises TypeError. Passing None means no request body, so if you need an explicit empty JSON body, use data='{}' with a Content-Type: application/json header or omit the body entirely.
Performance and Connection Considerations
When making multiple requests to the same host, reuse a requests.Session object. A session maintains a connection pool and reuses TCP connections, which reduces latency and avoids the overhead of establishing a new connection for each request.
session = requests.Session()
session.headers.update({"Authorization": "Bearer token"})
for page in range(1, 5):
response = session.get("https://api.example.com/items", params={"page": page})
# process responseSessions also persist cookies and allow you to set default headers. This is especially useful for API clients that authenticate once and then make many calls.
Set timeouts on every request to prevent hanging indefinitely. The timeout parameter accepts seconds or a tuple for connect and read timeouts separately.
response = requests.get("https://api.example.com/slow", timeout=(3, 10))Without a timeout, a network failure can leave your script blocked indefinitely. Always specify a reasonable timeout for production code.
For large uploads, consider streaming with data and a file-like object or generator; the requests library supports chunked transfer encoding. The json parameter is for complete JSON-serializable objects, not streaming generators.
When you combine query parameters, headers, and a JSON body, the request is built in a predictable order: the URL is constructed first, then headers are attached, and finally the body is encoded. Understanding this order helps you debug issues when a server returns unexpected errors.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.