Data sources, freshness & retention

Every metric in the API traces back to a platform. This page explains, platform by platform, how Listener gets the data, what it stores, when it refreshes and how long it keeps it. Where something is not built yet, it says so.

How Listener gets each platform’s data#

There are four ways data reaches Listener. A show can mix them.

When a show has not connected Sync, Spotify and Apple Podcasts numbers can be requested from the Listener team (POST /v1/data-requests); a person pulls them, so they arrive later than automated data. Substack podcast downloads can also be imported from Substack’s stats export.

X is read through a data provider first; when that returns nothing recent, Listener falls back to the official X API with its own credentials (not the show’s).

Posts added by URL#

Anyone with access to a cluster can paste a post URL to add it. Listener fetches the post right away and stores the numbers on the cluster node.

Megaphone URLs can’t be dropped; add Megaphone episodes from the show’s connected Megaphone library. The creator app (listener.com) recognises the same URLs, plus Substack posts.

Added posts refresh with their cluster, as described in Refresh schedule.

What is stored per post#

Each cluster node stores the latest value of each metric, not a history per post.

How a platform defines a view is the platform’s own definition: Listener stores the counter the platform reports and does not recompute it. Instagram now calls its play count “Views”; X reports views as impressions; Spotify numbers cover the Spotify app only.

For account-level LinkedIn analytics, where LinkedIn reports no impressions, Listener estimates impressions from reactions and flags the figure as estimated (impressions_estimated). Cluster reach never uses that estimate.

Refresh schedule#

Account data (a show’s channel or profile) and cluster posts refresh in different ways. All times are UTC.

Account data#

There is no fixed timer that refreshes every social account every day. Account data moves when someone opens Listener, presses Refresh, calls the refresh endpoint, or when a scheduled report is due. Spotify and Apple data without Sync arrives when the Listener team fulfils a data request.

Cluster posts#

Cluster posts therefore refresh only when a public page that shows them is viewed, or when someone refreshes them.

History and retention#

Windows longer than about 30 days read from daily history. Responses say so in coverage.history_used and explain gaps in coverage.warnings (see Time windows).

Disconnecting, deleting and leaving#

• Disconnecting a platform in Listener Networks removes that platform’s current data from the show. In the Listener creator app the data is kept and marked disconnected. In both apps, daily history for that platform is kept, and any Sync session is revoked first.
• Deleting a cluster, campaign or report deletes that document right away. Daily cluster reach entries already captured are not removed.
• Deleting a show removes the show record. Its daily history, clusters and other stored sub-records are not removed automatically today.
• Deleting an account is not self-serve yet. Email tech@listener.com to have an account and all of its data deleted.

Storage and security#

• Where data lives: Google Cloud Firestore in the nam5 location, a United States multi-region. Google encrypts Firestore data at rest by default.
• API keys and OAuth tokens issued by Listener are stored only as SHA-256 hashes and compared in constant time. A leaked database copy can’t be used to call the API.
• Webhook signing secrets are encrypted with AES-256-GCM before they are stored.
• Listener Sync sessions (Spotify, Apple Podcasts, Megaphone) are encrypted with AES-256-GCM and kept apart from the show record.
• Request logs never contain request or response bodies.

Restatements, deleted posts and shared accounts#

Restatements. When a platform revises a post’s numbers, the next refresh stores the new value, with two guards:

• A metric that comes back as 0 after being positive keeps its previous value, because a zero is far more often a provider hiccup than a real reset.
• Views, impressions and reach on a cluster post never move down. A platform lowering one of these (for example after removing invalid traffic) is not reflected on the post. Engagement counts such as likes can move down.

Daily history is re-folded from the latest stored series, so a revised day replaces the old value there.

Deleted or private posts. When a post can no longer be fetched (deleted, made private or blocked), its last numbers stay on the cluster and the cluster records a refresh error for that post. Deleted Instagram and Facebook posts are kept as archived posts with their last known numbers. Remove a post from a cluster with POST /v1/shows/{show_id}/clusters/{cluster_id}/nodes/remove if it should no longer count.

One account on several shows. A network can link the same Instagram, TikTok, Facebook or YouTube account to several shows. By default each show counts its own accounts. With social_count_mode=unique, network totals, timelines and platform splits count each shared account once, attributed to one show (suppressed_platforms_by_show says which copies were skipped). Per-show rankings and comparisons always use each show’s own accounts. Cluster reach does not deduplicate accounts. See Metrics glossary.

Platform limits and how staleness shows up#

Platforms and data providers limit how often Listener can call them. Listener spaces its calls, retries after 429 responses using the platform’s Retry-After, waits for YouTube’s daily quota to reset when it runs out, and budgets data-provider credits. When a limit or an outage stops a refresh, the previous numbers stay and the data simply ages.

The API reports that age instead of hiding it:

• freshness: for each platform, last_updated, age_hours and stale. A platform is stale when its data is more than 36 hours old or has never been updated. For several shows, the summary reports the oldest.
• stale_platforms: the platforms that are stale in the result.
• coverage.warnings: plain-language notes when growth was left out (fewer than half the previous window’s days have data), or when a window reaches before the data Listener holds.
• Cluster freshness: when each cluster was last refreshed, plus its refresh errors.

The Data freshness guide shows how to read these, and the analytics.refreshed and integration.stale events tell you when data moves or stops moving. The Listener API’s own limits are in Rate limits.