HTTP Caching

This page documents which connector responses the platform stores and reuses.

Caching is on by default, and the headers your API returns decide whether a response is stored. There is no connector setting for it and no way to clear a stored response. If you do not control the API, nothing is stored unless it already sends the headers below.

What gets cached

Property	Rule
Methods	GET and HEAD (a request for headers only). A stored HEAD response is never reused for a GET request, nor the reverse. A request with a Range header is never cached.
Status code	200 only.
Freshness	Cache-Control: max-age=<seconds> (how long the response stays fresh), or an Expires date that has not passed. s-maxage alone and Last-Modified alone do not allow caching. The platform never guesses a freshness lifetime.
Lifetime	The remaining freshness of the response, and never more than one hour. max-age=600 is reused for ten minutes and max-age=7200 for one hour. A response that arrives already aged (its Age header, or the time since its Date header) is reused for less.
Body	1 MiB (1,048,576 bytes) or less, measured as the response travels over the network, so a compressed response counts at its compressed size. A larger response is returned in full and not stored. A response whose body cannot be decoded fails the call and is not stored, so the next request reaches your API.
Failures	If the platform cannot read or write a stored response, the request goes to your API as usual and does not fail.

A stored response can be reused for up to one hour, so the data a widget shows can be up to an hour old. This is expected.

Responses that are never stored

A response is not stored when it carries any one of these:

Header	Meaning
Cache-Control: no-store	The API forbids storing the response.
Cache-Control: no-cache	The API requires revalidation before every reuse.
Cache-Control: private	The response is meant for one user.
Set-Cookie	The response sets a cookie.
Vary: *	The response depends on request details the platform cannot compare.

Cacheable response example

An API response like this one is stored and reused for ten minutes. public is not required, and max-age alone is enough:

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

{"location": "New York", "temperature": 21}

The same response with Cache-Control: private, max-age=600 is not stored.

Who can receive a stored response

A stored response is reused only for a request that matches the one that produced it on all of the following:

• the same connector;
• the same method and the same URL, including the query string;
• the same request body;
• the same headers, including Authorization and any API key header, apart from the instrumentation headers the platform adds.

Two connectors that send byte-identical requests do not share a stored response. A request with a different Authorization or X-API-Key value gets its own stored response.

Two users whose requests are identical share one stored response. A user-specific value in the URL, a header, or the body gives each user their own. A value that changes on every request, such as a timestamp, means a stored response is never reused. Each distinct value of an overridable query parameter is stored separately. If a response is specific to one user and the request carries nothing that identifies that user, the API should send Cache-Control: private.

Test Connection and confirming reuse

Test Connection always sends the request to your API, for a saved connector and for an unsaved configuration, so it never shows a reused response. For a live connector call, the cache_hit field of the X-Connector-Timing header, described in Testing & Debugging, reports whether the response was served from the stored copy. It is always false for a composite connector.

Cookies

Connector requests do not carry cookies set by earlier responses, including earlier steps of a composite connector (see Build a Composite Connector). A Cookie header that you set on the connector itself is still sent.

Next Steps

• Testing & Debugging — Timing headers, including whether a call was served from cache
• Configuration — Full list of connector fields including URL, method, and headers