Skip to content
Listener.comDevelopers

Analytics

Account-level reach, timelines, rankings, platform stats and recent content. These endpoints cost 2 rate-limit tokens.

Reach summary

GET/v1/analytics/reach
analytics:read

The analytics-page KPI cards: total, YouTube, audio, social and newsletter reach for the window, with previous-period values, guarded growth, per-platform totals, coverage and freshness.

categories is a case-insensitive substring match on show categories; platforms restricts the totals (aliases accepted); social_count_mode=unique counts an account shared by several shows once. Newsletter opens are their own category and part of total. For the daily series use GET /v1/analytics/timeline; for per-show numbers GET /v1/analytics/shows.

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

Freshness. freshness maps each platform to {last_updated, age_hours, stale} (stale = older than 36 h); stale_platforms lists them. A zero usually means a stale connector, not a zero audience.

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.reach()client.analytics.reach()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • social_count_modestring
    all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only).
    One ofallunique

    Default "all"

  • metricstring
    Which measure to report.
    One ofreachengagement

    Default "reach"

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.

Returns

200

OK

  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • coverageobjectrequired
    How much of the window actually has data (design §2).
    Show child attributesHide child attributes
  • computed_atstringrequired
  • totalobjectrequired
    Show child attributesHide child attributes
  • youtubeobjectrequired
    Show child attributesHide child attributes
  • audioobjectrequired
    Show child attributesHide child attributes
  • socialobjectrequired
    Show child attributesHide child attributes
  • newsletterobjectrequired
    Beehiiv + Substack newsletter opens; part of total on the analytics page.
    Show child attributesHide child attributes
  • objectstringrequired
  • freshnessmap of object
    platform → oldest freshness across the scoped shows.
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • show_idsarray of strings
    Shows included after show_ids/categories filtering.
  • missing_show_idsarray of strings
  • filtersobject
  • cache_age_secondsnumber

    Default 0

  • notestringnullable
  • metricstring
    One ofreachengagement

    Default "reach"

  • social_count_modestring
    One ofallunique

    Default "all"

  • per_platformmap of integer
  • previous_per_platformmap of integer
  • suppressed_platforms_by_showmap of array of strings
    Unique mode only: show → platforms skipped because another show is canonical for the same account.
  • shows_in_totalsinteger

    Default 0

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Reach timeline

GET/v1/analytics/timeline
analytics:read

The daily performance series behind the analytics chart (date, total, per platform, running cumulative) with totals, growth and the peak day. chart_type=cumulative returns running sums; include_previous=true adds the baseline window's rows; include_per_show=true adds one series per show (never de-duplicated).

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.timeline()client.analytics.timeline()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • social_count_modestring
    all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only).
    One ofallunique

    Default "all"

  • metricstring
    Which measure to report.
    One ofreachengagement

    Default "reach"

  • chart_typestring
    daily values or a cumulative running total.
    One ofdailycumulative

    Default "daily"

  • include_previousboolean
    Also return the previous period's series.

    Default false

  • include_per_showboolean
    Also return a per-show breakdown.

    Default false

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.

Returns

200

OK

  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • coverageobjectrequired
    How much of the window actually has data (design §2).
    Show child attributesHide child attributes
  • computed_atstringrequired
  • metricstringrequired
    One ofreachengagement
  • chart_typestringrequired
    One ofdailycumulative
  • rowsarray of objectsrequired
    Show child attributesHide child attributes
  • totalintegerrequired
  • previous_totalintegerrequired
  • objectstringrequired
  • freshnessmap of object
    platform → oldest freshness across the scoped shows.
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • show_idsarray of strings
    Shows included after show_ids/categories filtering.
  • missing_show_idsarray of strings
  • filtersobject
  • cache_age_secondsnumber

    Default 0

  • notestringnullable
  • social_count_modestring
    One ofallunique

    Default "all"

  • previous_rowsarray of objectsnullable
    Show child attributesHide child attributes
  • growthnumbernullable
  • per_platformmap of integer
  • previous_per_platformmap of integer
  • peak_dayobjectnullable
    Show child attributesHide child attributes
  • per_showmap of array of objectsnullable
    show id → daily totals (include_per_show=True).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Rank shows

GET/v1/analytics/shows
analytics:read

Every show in scope ranked by reach for the window (total, YouTube, audio, social, newsletter, per platform, previous period, growth). Rows are never de-duplicated, so their sum can exceed GET /v1/analytics/reach in unique mode. sort_by=growth puts shows without a baseline last.

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.shows()client.analytics.shows()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • sort_bystring
    Sort field.
    One oftotalyoutubeaudiosocialgrowth

    Default "total"

  • metricstring
    Which measure to report.
    One ofreachengagement

    Default "reach"

  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.
  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Compare two shows

GET/v1/analytics/compare
analytics:read

Two shows side by side for the window: category reach, growth, per-platform totals, optional daily series (include_series=true) and head-to-head deltas with a winner per metric. Never de-duplicated.

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.compare()client.analytics.compare()

Query parameters

  • show_id_astringrequired
  • show_id_bstringrequired
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • metricstring
    Which measure to report.
    One ofreachengagement

    Default "reach"

  • include_seriesboolean

    Default false

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.

Returns

200

OK

  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • coverageobjectrequired
    How much of the window actually has data (design §2).
    Show child attributesHide child attributes
  • computed_atstringrequired
  • aobjectrequired
    Show child attributesHide child attributes
  • bobjectrequired
    Show child attributesHide child attributes
  • head_to_headarray of objectsrequired
    Show child attributesHide child attributes
  • objectstringrequired
  • freshnessmap of object
    platform → oldest freshness across the scoped shows.
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • show_idsarray of strings
    Shows included after show_ids/categories filtering.
  • missing_show_idsarray of strings
  • filtersobject
  • cache_age_secondsnumber

    Default 0

  • notestringnullable
  • metricstring
    One ofreachengagement

    Default "reach"

  • overall_winnerstringnullable
    One ofabtie

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Platform distribution

GET/v1/analytics/distribution
analytics:read

The platform share of views (reach), engagement or followers: value and percent per platform. Views and engagement sum the window's daily performance; followers are live counts from each platform and ignore the window (deliberately disconnected platforms count 0).

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.distribution()client.analytics.distribution()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • social_count_modestring
    all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only).
    One ofallunique

    Default "all"

  • metricstring
    Which measure to report.
    One ofviewsfollowersengagement

    Default "views"

  • include_zeroboolean

    Default false

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.

Returns

200

OK

  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • coverageobjectrequired
    How much of the window actually has data (design §2).
    Show child attributesHide child attributes
  • computed_atstringrequired
  • metricstringrequired
    One ofviewsfollowersengagement
  • entriesarray of objectsrequired
    Show child attributesHide child attributes
  • totalintegerrequired
  • sourcestringrequired
    Where the values come from: daily performance (views/engagement) or live follower counts (followers).
  • objectstringrequired
  • freshnessmap of object
    platform → oldest freshness across the scoped shows.
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • show_idsarray of strings
    Shows included after show_ids/categories filtering.
  • missing_show_idsarray of strings
  • filtersobject
  • cache_age_secondsnumber

    Default 0

  • notestringnullable
  • social_count_modestring
    One ofallunique

    Default "all"

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Dashboard KPIs

GET/v1/analytics/dashboard
analytics:read

The network dashboard: eight KPI tiles (followers, impressions, likes, comments, posts, engagement rate, downloads, EMV), the EMV breakdown, a per-show table (table_mode = reach, audience or demographics) and the top content per platform.

time_range is 7d, 30d or 90d (or start_date + end_date spanning at most 90 days). On 90 days, impressions, downloads and engagement rate cover the full window from stored history (growth like-for-like), while likes, comments, posts and top content stay on the last 30 days with no growth; metric_windows and each tile's window say which window a value covers. EMV values audio downloads at the long-form CPM and every other impression at the short-form CPM, plus likes × like rate and comments × comment rate, using the network's default EMV rates (defaults 25 / 20 / 0.25 / 1.25).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.dashboard()client.analytics.dashboard()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • social_count_modestring
    all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only).
    One ofallunique

    Default "all"

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.
    One of7d30d90d

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.
  • table_modestring
    One ofreachaudiencedemographics

    Default "reach"

  • top_content_per_platforminteger0 to 10

    Default 3

Returns

200

OK

  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • coverageobjectrequired
    How much of the window actually has data (design §2).
    Show child attributesHide child attributes
  • computed_atstringrequired
  • time_rangestringrequired
  • table_modestringrequired
    One ofreachaudiencedemographics
  • tilesarray of objectsrequired
    Show child attributesHide child attributes
  • emvobjectrequired
    Show child attributesHide child attributes
  • showsarray of objectsrequired
    Show child attributesHide child attributes
  • objectstringrequired
  • freshnessmap of object
    platform → oldest freshness across the scoped shows.
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • show_idsarray of strings
    Shows included after show_ids/categories filtering.
  • missing_show_idsarray of strings
  • filtersobject
  • cache_age_secondsnumber

    Default 0

  • notestringnullable
  • per_platform_reachmap of integer
  • top_contentmap of array of objects
    platform → top 3 items in the window by plays/views/impressions (last 30 days on a 90d window).
    Show child attributesHide child attributes
  • metric_windowsmap of string
    tile key → window its value covers. On 90d: impressions/downloads/engagement_rate cover 90 days (history-backed); likes/comments/posts/top_content are the last 30 days (no long-range source); followers are live; EMV is mixed.

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Rank hosts

GET/v1/analytics/hosts
analytics:read

The Hosts tab: every host across the shows in scope with their own per-platform audience, YouTube and social splits, the shows they appear on and those shows' reach in the window. A host on several shows is one row (counts are never summed). Ranked by personal audience; sort_by=shows_reach ranks by the shows' window reach.

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.hosts()client.analytics.hosts()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • sort_bystring
    Sort field.
    One ofaudienceyoutubesocialshows_reachname

    Default "audience"

  • searchstringnullable
    Case-insensitive text filter.
  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.
  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Shared-account (dedup) view

GET/v1/analytics/accounts
analytics:read

Connected accounts shared by several shows (the same YouTube channel, Instagram handle, Spotify show …), which show is canonical, and the platforms suppressed per show in social_count_mode=unique. Suppression applies to overview totals, timelines and distributions only, never to rankings or comparisons.

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.accounts()client.analytics.accounts()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.

Returns

200

OK

  • platforms_checkedarray of stringsrequired
  • has_duplicatesbooleanrequired
  • duplicate_platformsarray of stringsrequired
  • groupsarray of objectsrequired
    Show child attributesHide child attributes
  • duplicate_groupsarray of objectsrequired
    Show child attributesHide child attributes
  • applies_toarray of stringsrequired
  • never_applied_toarray of stringsrequired
  • show_idsarray of stringsrequired
  • computed_atstringrequired
  • objectstringrequired
  • suppressedmap of array of strings
    show id → platforms skipped in unique mode.
  • missing_show_idsarray of strings
  • cache_age_secondsnumber

    Default 0

  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

List show categories

GET/v1/analytics/categories
analytics:read

The distinct show categories in the workspace (the analytics Topics filter) with the shows in each; use them as categories values. Placeholder categories such as "Category 3" are dropped unless include_placeholders=true.

  • Costs 2 rate-limit tokens.

SDKlistener.analytics.categories()client.analytics.categories()

Query parameters

  • include_placeholdersboolean

    Default false

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

A show's platform stats

GET/v1/shows/{show_id}/platforms
analytics:read

One show's per-platform metric blocks (views, plays or downloads, followers, engagement, growth against the previous period), audience signals (demographics, geography, retention, traffic sources) and freshness. platform is a platform key (aliases accepted) or all; time_range is 7d, 30d or 90d; include_raw=true appends the stored platform data with secrets removed and arrays capped at 200 items.

On 90 days the likes, comments, posts and follower deltas stay on the last 30 days; each block's window_totals adds the platform's 90-day reach and engagement with growth (null under 50 % coverage). metric_windows states which window each part covers.

Freshness. freshness maps each platform to {last_updated, age_hours, stale} (stale = older than 36 h); stale_platforms lists them. A zero usually means a stale connector, not a zero audience.

  • Costs 2 rate-limit tokens.

SDKlistener.shows.platforms.list()client.shows.platforms.list()

Path parameters

  • show_idstringrequired
    A show id in this workspace (see GET /v1/shows).

Query parameters

  • platformstring
    A platform name (e.g. youtube, spotify, applePodcasts, instagram).

    Default "all"

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.
    One of7d30d90d

    Default "30d"

  • include_rawboolean

    Default false

Returns

200

OK

  • showobjectrequired
    The minimal show reference embedded in cross-show results.
    Show child attributesHide child attributes
  • time_rangestringrequired
    One of7d30d90d
  • windowobjectrequired
    The resolved analytics window (from `core.dates.Window.as_dict()`).
    Show child attributesHide child attributes
  • platformsarray of objectsrequired
    Show child attributesHide child attributes
  • requested_platformstringrequired
  • computed_atstringrequired
  • objectstringrequired
  • metric_windowsmap of string
    Which window each part of the response covers. On 90d the ported metric blocks stay on the last 30 days (no long-range source for likes, comments, posts, follower deltas); window_totals covers the full 90 days.
  • freshnessmap of object
    Show child attributesHide child attributes
  • stale_platformsarray of strings
  • missing_show_idsarray of strings
  • cache_age_secondsnumber

    Default 0

  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Recent posts and content

GET/v1/content
analytics:read

Recent content across platforms (Instagram reels, TikToks, X posts, LinkedIn / Threads / Facebook posts, YouTube videos, newsletters, Art19 / Omny episodes) published inside the window, newest first, with per-item metrics. Captions are truncated to 280 characters. group_by=day or platform adds meta.groups for the page; limit_per_platform caps each platform before pagination (0 = no cap).

Windows. time_range is 7d, 14d, 30d, 90d, 180d, 365d, all (rolling UTC days, today inclusive) or a calendar quarter such as 2026-Q2 (a bare Q2 means the current year). start_date + end_date (YYYY-MM-DD, inclusive, both required) override it. Results carry window and coverage.

Growth. Growth compares against the equal-length window immediately before (the previous quarter for quarter tokens). It is null (show it as "—", never 0) when the previous window has under 50 % day coverage. Windows longer than 30 days read stored history and compare like-for-like: only platforms whose data covers at least half of the previous window, both windows summed over those platforms (coverage.growth_platforms).

  • Costs 2 rate-limit tokens.

SDKlistener.content.list()client.content.list()

Query parameters

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
  • categoriesarray of stringsnullable
    Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values.
  • platformsarray of stringsnullable
    Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values.
  • social_count_modestring
    all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only).
    One ofallunique

    Default "all"

  • group_bystring
    Group the results by this field.
    One ofnonedayplatform

    Default "none"

  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • limit_per_platforminteger0 to 500

    Default 0

  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.

    Default "30d"

  • start_datestringnullable
    First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range.
  • end_datestringnullable
    Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range.
  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error