HTTP QUERY Method Explained: The New Standard for Safe Requests with a Body

The HTTP QUERY method is now an official HTTP standard. It is safe, idempotent, and allows a request body, and fixes a decade-long design gap that forced developers to use POST for read-only search operations.

HTTP QUERY is a new HTTP method that works like GET (safe, idempotent, cacheable) but accepts a request body like POST. It is designed for complex queries where the parameters are too large or too structured to fit in a URL query string. The method standardizes what teams have been doing informally with POST for years.

Vantaj added QUERY method support alongside this standardization. You can now monitor any endpoint that accepts QUERY requests, with full body configuration, header support, and multi-region confirmation checks.

Why HTTP needed a new method

HTTP has had the same core set of methods since RFC 2616 in 1999: GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE. RFC 9110, published in June 2022, updated the semantics but kept the same method set.

The gap was always GET: the spec says GET SHOULD NOT have a body, and many HTTP implementations treat a GET body as undefined behavior, strip it silently, or reject the request. But developers needed a way to send complex, structured query parameters without relying on URL query strings that have practical length limits (around 2,000 characters in many browsers and servers) and that cannot carry structured data naturally.

The workaround everyone reached for was POST. GraphQL uses POST /graphql with a JSON body. Elasticsearch uses POST /_search with a JSON query. SPARQL endpoints accept POST with query strings. These work, but they misrepresent the semantics: POST signals a state-changing operation. Using POST for read-only queries breaks HTTP caching, confuses intermediate proxies, and makes it impossible for clients and servers to reason correctly about idempotency.

The HTTP Working Group at the IETF tracked this problem for years. The solution: a new method called QUERY.

What QUERY defines

QUERY has three core properties:

A QUERY request looks like this:

QUERY /products/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "filters": {
    "category": "electronics",
    "price_max": 500,
    "in_stock": true
  },
  "sort": "price_asc",
  "page": 1,
  "per_page": 20
}

The server processes the body as the query specification and returns results. The response carries standard cache headers:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: max-age=60
Vary: Authorization

{ "results": [...], "total": 347 }

Because QUERY is safe and idempotent, HTTP caches (CDNs, reverse proxies, browser caches) can cache the response and serve it for repeated identical requests. POST cannot do this by default.

The Content-Type requirement

Unlike GET, a QUERY request MUST include a Content-Type header identifying the format of the query body. The spec does not mandate a specific content type, APIs can define their own query formats.

Common choices:

A server that does not understand the Content-Type returns 415 Unsupported Media Type.

Who benefits from QUERY

GraphQL APIs

GraphQL currently uses POST /graphql for queries, mutations, and subscriptions alike. Queries are read-only operations, they should be safe and idempotent. Using POST for them means:

• CDNs cannot cache query responses by default
• APMs and monitoring tools show all traffic as POST, obscuring query vs. mutation rates
• Load balancers cannot make routing decisions based on operation type

With QUERY, a GraphQL server can accept QUERY /graphql for read-only operations and POST /graphql for mutations. Clients and infrastructure components can then cache, route, and monitor them independently.

Elasticsearch and OpenSearch

Elasticsearch has supported GET /_search with a request body for years, relying on non-standard behavior that many HTTP libraries handle inconsistently. It also accepts POST /_search as an alternative. QUERY provides the correct semantic for these operations. Teams running Elasticsearch can now send search requests as QUERY and get predictable caching and proxy behavior.

SPARQL endpoints

SPARQL, the query language for linked data and knowledge graphs, already defined a POST-based query submission mechanism. The QUERY method aligns with the read-only semantics SPARQL queries carry. Research institutions and enterprise knowledge graph teams were early advocates for the method.

Complex search and filter APIs

Any REST API with a search endpoint hits the same wall: faceted search with 10 filter dimensions does not fit cleanly in a URL. The standard advice was to POST the search body to a dedicated endpoint. QUERY removes the semantic awkwardness from that pattern.

Caching QUERY responses

Caching is one of the most concrete benefits. For a GET request, caches key on the URL and vary on headers. For a QUERY request, caches key on the URL AND the request body.

The RFC specifies that implementations may use a hash of the request body as part of the cache key. Practical implementations in CDNs like Cloudflare, Fastly, and Varnish are adding QUERY support. Once in place, identical searches return cached responses without hitting your origin server.

For high-traffic search endpoints, this is the same performance gain teams previously achieved by building a dedicated cache layer on top of POST endpoints.

Status codes with QUERY

QUERY follows the same status code semantics as other HTTP methods. The common cases:

A 405 Method Not Allowed response MUST include an Allow header listing the supported methods. If you receive one while testing a new API, check whether the server has added QUERY support.

Monitoring QUERY endpoints

QUERY endpoints need the same monitoring coverage as GET and POST endpoints. The method is new; the failure modes are familiar.

What to check:

1. Availability: Is the QUERY endpoint reachable? Returns 200 for a known valid query?
2. Response correctness: Does the body contain expected fields (results, total, pagination data)?
3. Latency: How long does the query take? Search endpoints are database-intensive and degrade before they fail.
4. Error rate: Are 400s or 422s increasing? That signals schema drift between clients and the server.
5. Cache hit rate: If your CDN supports QUERY caching, is the cache actually being used?

Because QUERY is idempotent and safe, you can run the same monitor check repeatedly without creating test data, consuming write quotas, or triggering side effects. That makes it cleaner to monitor than POST endpoints, where repeated calls may create duplicate resources.

Read how to monitor your API endpoints for the full setup guide.

How Vantaj monitors QUERY endpoints

Vantaj recently added QUERY method support to its HTTP monitor configuration. You can now create a monitor that sends a QUERY request with:

• A custom request body (JSON, GraphQL, SPARQL, or any text format)
• Content-Type and any additional headers your API requires
• Response assertions on status code, body content, and latency threshold
• Check intervals from 30 seconds to 5 minutes

Each check runs from up to 10 global regions. Vantaj only alerts when checks fail in multiple regions simultaneously, cutting false positives from single-node blips that self-resolve. If your search API goes down in Frankfurt but responds normally from every other region, that is a regional routing issue, not a service outage. You learn the difference before you page anyone.

A QUERY monitor config in Vantaj looks similar to any other HTTP monitor:

Method: QUERY
URL: https://api.example.com/products/search
Content-Type: application/json
Body: {
  "filters": { "in_stock": true },
  "page": 1
}
Assert: status = 200
Assert: body contains "results"
Assert: response_time < 1000ms
Regions: 10 (all)

Set the alert threshold to require two or more regions to fail before paging. This keeps your on-call rotation sane when a single probe has a bad day.

See the uptime monitoring guide for alert threshold recommendations, and how to reduce false positive alerts for the full tuning approach.

What to do now

If your team builds or depends on APIs with complex query patterns, three things are worth doing now:

1. Check your monitoring tool's support list. Not every tool added QUERY support yet. If yours does not support it, your QUERY endpoints have no automated check. Vantaj supports it today.
2. Review your GraphQL monitoring. If you monitor GraphQL via POST, consider adding a parallel QUERY check once your server adds support. You get response caching and correct semantic tagging in your APM.
3. Update your API design documentation. Teams that currently send read-only searches as POST should note QUERY as the correct method for new endpoints. Migration of existing endpoints is optional. POST still works. New endpoints benefit from correct semantics from day one.

The HTTP QUERY method does not change what APIs do. It gives the industry a shared vocabulary for an operation that was already happening everywhere, and makes caching, routing, and monitoring work correctly around it.

Frequently asked questions

Is HTTP QUERY supported by browsers?

Browser fetch() API and XMLHttpRequest do not restrict which method string you send. You can use fetch('/search', { method: 'QUERY', body: JSON.stringify(query) }) today. Server support depends on your framework. Most have added QUERY as a recognized method token as of 2025-2026.

Do I need to update my API to use QUERY?

No. Existing POST-based search endpoints keep working. QUERY is a new option for new endpoints or for servers that choose to add it. The HTTP spec is additive, not breaking.

Will my CDN cache QUERY requests?

Cloudflare, Fastly, and Varnish have announced or shipped QUERY support. Check your CDN's changelog. If your CDN does not yet support QUERY caching, QUERY requests pass through to origin like any uncacheable request.

How does QUERY affect API rate limits?

Rate limiting does not change with QUERY. If your API rate-limits by authenticated user or IP, QUERY requests count the same as GET or POST. Add QUERY to your rate-limit allow list if your middleware pattern-matches on method.

Is QUERY safe for REST APIs that use query strings?

Yes. QUERY does not replace URL query strings. You can combine a request body with URL query strings in a QUERY request, the same way POST endpoints accept both.