Metrics freshness
Metrics are read live from Meta and Whop. A read can come from a short cache, up to 5 minutes old for today and up to 1 hour for past days, and asOf tells you when it was read.
Koast doesn't keep its own copy of your ad metrics. Every metrics number comes from the ad platform, Meta or Whop, at read time. Koast may answer a repeated metrics read from a short cache.
Which endpoints
| Endpoint | Operation |
|---|---|
GET /v1/brands/{brandId}/launches/{launchId}/metrics | get-metrics |
GET /v1/brands/{brandId}/launches/{launchId}/insights/daily | get-insights-daily |
GET /v1/brands/{brandId}/launches/{launchId}/creative-fatigue | compute-creative-fatigue |
GET /v1/brands/{brandId}/ad-accounts/{accountId}/overview | get-account-overview |
GET /v1/brands/{brandId}/ad-accounts/{accountId}/campaigns | list-account-campaigns |
GET /v1/brands/{brandId}/launches with accountId | list-koast-batches |
Nothing else is cached. Writes, delivery status (get-ad-delivery-status), targeting and option lookups always read live.
How old a number can be
| Date range | Cached for up to |
|---|---|
| Includes today, in the ad account's timezone | 5 minutes |
| Past days only | 1 hour |
A publish, a live budget edit or a status change made through Koast clears the cache for that ad account, so your next read is live.
Your access is checked on every call before the cache is consulted. A cached number is never served to a credential that couldn't read it live.
asOf
Every response from these endpoints carries asOf: the time of the live read behind the numbers. Compare it with the response's Date header to see how old the numbers are.
Two reads a few seconds apart, at 04:52 UTC:
curl "https://api.koast.ai/v1/brands/1/launches/cmv0dbqmv0001vct12clu58vk/metrics?level=campaign&datePreset=today" \
-H "Authorization: Bearer $KOAST_API_KEY"{
"level": "campaign",
"campaigns": [],
"isExample": false,
"dataAvailability": "NO_LIVE_ENTITIES",
"datePreset": "today",
"campaignLaunchId": "cmv0dbqmv0001vct12clu58vk",
"asOf": "2026-10-09T04:52:50.285Z"
}curl "https://api.koast.ai/v1/brands/1/launches/cmv0dbqmv0001vct12clu58vk/metrics?level=campaign&datePreset=last_7d" \
-H "Authorization: Bearer $KOAST_API_KEY"{
"level": "campaign",
"campaigns": [],
"isExample": false,
"dataAvailability": "NO_LIVE_ENTITIES",
"datePreset": "last_7d",
"campaignLaunchId": "cmv0dbqmv0001vct12clu58vk",
"asOf": "2026-10-09T04:40:20.512Z"
}last_7d doesn't include today, so it was served from a read taken 12 minutes earlier. The today read is seconds old.
null is not 0
When a metric can't be determined, it is null, never 0. A 0 is a measured zero. Treat null as unknown: don't pause an ad or alert on it.
Polling
- Polling more often than every 5 minutes for today, or every hour for past days, mostly returns the same
asOf, and still costs you rate limit. - To react to new numbers, subscribe to
metrics.updated(hourly per ad account) andspend.day_closed(once per day, after midnight in the account's timezone) instead. See Webhooks.
Rate limits
Each organization gets 300 reads and 60 writes a minute, with at most 10 requests in flight. Read the RateLimit headers and back off on 429.
Versioning
v1 only ever grows. New endpoints, optional parameters and response fields arrive without notice. A breaking change ships as /v2, next to v1.