QUERY
The HTTP QUERY method requests the server to process enclosed content as a safe, idempotent query against the target resource, combining the safety of GET with the ability to include a request body.
Usage
Complex queries often exceed practical URI length limits. Search parameters, GraphQL operations, SQL expressions, and structured filter objects are difficult to encode as query strings. GET carries no body, forcing these inputs into the URI. POST accepts a body but is neither safe nor idempotent, preventing caches and intermediaries from optimizing repeated requests.
QUERY fills this gap. The method sends query content in the request body while preserving the safe and idempotent semantics of GET. Responses are cacheable, and intermediaries are free to retry failed requests without risk of unintended side effects.
Properties
| Property | Value |
|---|---|
| Safe | Yes |
| Idempotent | Yes |
| Cacheable | Yes |
The request requires a Content-Type header describing the query format. Servers reject requests with:
- Missing or inconsistent Content-Type: 400 Bad Request
- Unsupported query media type: 415 Unsupported Media Type
- Valid syntax but unprocessable query: 422 Unprocessable Content
- Unsupported response format: 406 Not Acceptable
Equivalent resources
A server processing a QUERY request defines an equivalent resource, one responding to GET and representing the combination of the query content and the target resource. This concept underpins three response patterns:
- Include a Content-Location header identifying a resource containing the query results, retrievable via GET.
- Include a Location header identifying the equivalent resource URI, allowing clients to repeat the query via GET without resending the body.
- Redirect with 303 and a Location header pointing to a GET-accessible URI for the results.
Redirects
Unlike POST, redirect responses preserve the QUERY method. 301, 302, 307, and 308 redirects all repeat the QUERY request to the new URI without converting to GET. Only 303 switches the method to GET, directing the client to retrieve results from a different URI.
Caching
QUERY responses are cacheable. The cache key incorporates the request content and related metadata in addition to the target URI. Caches normalize insignificant differences in the request body (such as removing content encoding or normalizing based on media type semantics) for cache key generation only.
CORS
QUERY is not a CORS-safelisted method. Cross-origin QUERY requests require a preflight OPTIONS request before the browser sends the actual request.
Accept-Query
The Accept-Query response header field declares
the media types a server accepts
for QUERY
requests. The field uses
Structured Fields List
syntax.
Accept-Query: application/graphql, application/sql
Servers include this header in responses to inform clients about supported query formats for a given resource.
Note
QUERY is defined in an IETF Standards Track document (draft-ietf-httpbis-safe-method-w-body), currently in the RFC Editor Queue as a Proposed Standard. No major browser supports QUERY natively, and server-side support is emerging while the specification completes the publication process.
Example
A GraphQL query sent to an API endpoint. The request body contains the full query, avoiding URI length constraints.
QUERY /api/graphql HTTP/1.1
Host: api.example.re
Content-Type: application/graphql
{
users(role: "admin") {
id
name
email
}
}
HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /api/graphql/results/a7f3
{"data":{"users":[{"id":"1","name":"Ada","email":"ada@example.re"}]}}
A structured search with URL-encoded form data. The query exceeds typical URI length limits due to multiple filter parameters.
QUERY /search HTTP/1.1
Host: www.example.re
Content-Type: application/x-www-form-urlencoded
q=distributed+systems&category=books&year=2025&sort=relevance&lang=en&format=hardcover
HTTP/1.1 303 See Other
Location: /search/results/b8e2
The 303 redirect points to a cached result set accessible via GET, allowing bookmarking and sharing of the query results.
A conditional query using If-None-Match to avoid transferring unchanged results.
QUERY /feed HTTP/1.1
Host: www.example.re
Content-Type: application/x-www-form-urlencoded
If-None-Match: "v42"
topic=http&since=2025-01-01
HTTP/1.1 304 Not Modified
ETag: "v42"
Takeaway
The QUERY method enables safe, idempotent, cacheable requests with a body, filling the gap between GET (no body) and POST (not safe or idempotent) for complex query operations. Redirect responses preserve the method, cache keys incorporate the request body, and cross-origin requests require a CORS preflight.