Caching and freshness
How fresh the data is
The API never caches a response. Every request is answered from the database at the moment you make it, and every response is marked Cache-Control: private, no-store. A value you read is the value stored right then.
What that does not mean is real-time. Asky data is produced by pipelines that run on a schedule measured in hours: prompts execute daily, citations are extracted and classified after each run, and website crawls run on their own cadence. So a figure is as fresh as the last pipeline run that produced it, and asking again a minute later returns the same number because nothing upstream has changed.
The distinction matters if you are building on this. The API adds no delay of its own, so it always agrees with the app. If a number looks stale, the pipeline has not run yet, and calling more often will not change that.
Polling
The most common mistake with an analytics API is polling far faster than the data changes. Polling every minute for a figure that updates once a day returns the same value roughly 1,400 times and burns your rate limit doing it.
| Data | Reasonable interval |
|---|---|
| Visibility, competitors, citations, prompt metrics | Daily, after the pipeline completes |
| Prompt executions and responses | Daily |
| Website pages and crawler activity | Daily |
| Opportunities and content drafts | Hourly at most |
Match your schedule to the pipeline, not to your rate limit. For a daily sync, run it once and pull a window that overlaps the previous run. See incremental sync.
Conditional requests
Conditional requests are not supported yet. There is no ETag and no 304 Not Modified, so every request transfers a full body. If you poll, budget for that.
ETag support is planned. It will be additive when it lands: responses gain a header, and a client that ignores it keeps working exactly as before.
Why responses are never cached
Responses are marked Cache-Control: private, no-store. They are specific to your key and must never be stored in a shared or public cache: a CDN or a shared proxy holding an Asky response would be serving one tenant’s analytics to whoever asks next.
no-store is deliberate and stricter than private. Cache in your own application if you want to, where you control the key and the tenant; do not rely on an HTTP cache in between. If you do, key your cache on the full request, including every filter.
The one exception is /v1/openapi.json, which is identical for everyone, carries no tenant data, and is public, max-age=300.
Consistency across requests
Each request is answered independently. Two requests a moment apart can straddle a pipeline run, so figures fetched separately may not reconcile exactly.
Where consistency matters, such as a dashboard where a total must equal the sum of its parts, fetch the underlying data once and derive the breakdowns locally rather than issuing one request per panel. That is also fewer requests.