Skip to content
Listener.comDevelopers

Data freshness

How current each platform’s numbers are, how to detect stale data, and how to refresh it.

2 min read

Listener collects data from each connected platform on its own schedule, so different platforms can be a few hours apart. The API never hides that: every result built from platform data says how fresh it is.

Reading freshness#

freshness
{
  "freshness": {
    "youtube": { "last_updated": "2026-10-14T06:12:00Z", "age_hours": 3.3, "stale": false },
    "spotify": { "last_updated": "2026-10-12T04:40:00Z", "age_hours": 52.8, "stale": true }
  },
  "stale_platforms": ["spotify"]
}

A platform is stale when its data has not advanced for more than 36 hours.

Zero is usually stale, not silent:

Zero is usually stale, not silent

When a number looks too low or reads zero, check freshness first. A stale or disconnected connection is a far more common cause than an audience that disappeared. Show the freshness next to the number so your users can tell too.

Where to look#

NeedEndpoint
Freshness for the whole workspaceGET /v1/me (data_freshness, stale_platforms)
Connection state per show and platformGET /v1/integrations
What is stale and how it can be refreshedGET /v1/integrations/status
Freshness behind a specific numberthe freshness field of that response

GET /v1/integrations lists each show and platform as connected, pending or disconnected, with the last update, whether it is stale, how it can be refreshed (server, manual_request or none) and the last error the connection reported.

Getting notified#

Three events cover freshness, so you do not have to poll:

  • analytics.refreshed: a show’s platform data advanced. Re-read the analytics you care about.
  • integration.stale: a connected platform has not advanced for more than 36 hours.
  • integration.disconnected: a connection stopped working and needs someone to reconnect it in the app.

Refreshing data#

Most platforms can be refreshed on demand with POST /v1/shows/{show_id}/platforms/{platform}/refresh and the refresh:write scope, one platform per call:

  • Metered platforms (TikTok, X, Facebook, Instagram, Threads, LinkedIn) spend scraping credits, so they also need confirm: true.
  • Spotify refreshes asynchronously; the response says requested.
  • Apple Podcasts cannot be refreshed on demand. File a data request instead.
curl
curl -X POST https://api.listener.com/v1/shows/8sQe1v0x2kTq/platforms/instagram/refresh \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

For Spotify or Apple Podcasts numbers that are missing or stale, POST /v1/data-requests (with confirm: true) asks the Listener team to pull them; it creates work for a person, so a request already pending for the same show and platform is refused. Use dry_run: true first to see what would be refreshed or requested.

Reconnecting a platform account (for example after a password change) happens in the app, under Integrations. The API cannot connect platform accounts.