Skip to content
Listener.comDevelopers

Refresh

Metered actions: platform refreshes and Spotify / Apple data requests.

Refresh a show's platform data

POST/v1/shows/{show_id}/platforms/{platform}/refresh
refresh:writeNeeds confirm=trueSupports dry_run

Refresh one platform's data for one show now and return the status (updated, skipped, requested, error), last update before and after, and the provider-call estimate. Metered scraper platforms (tiktok, twitter, facebook, instagram, threads, linkedin) spend credits and need "confirm": true; spotify is asynchronous (requested); applePodcasts cannot be refreshed on demand (use POST /v1/data-requests).

  • Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.
  • Requires "confirm": true; without it the API answers 409 confirmation_required with the exact preview.

SDKlistener.shows.platforms.refresh()client.shows.platforms.refresh()

Path parameters

  • show_idstringrequired
    A show id in this workspace (see GET /v1/shows).
  • platformstringrequired
    A platform name (e.g. youtube, spotify, applePodcasts, instagram).
    One ofyoutubeinstagraminstagramBusinesstiktoktwitterfacebookthreadslinkedinbeehiivsubstacksimplecasttransistorart19captivateomnystudiospotifyapplePodcasts

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

  • confirmboolean
    Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.

    Default false

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error

File a Spotify / Apple data request

POST/v1/data-requests
refresh:writeNeeds confirm=trueSupports dry_run

File a Spotify or Apple Podcasts data request with the Listener operations team and return the request written (status pending). Needs "confirm": true because it creates work for a person. show_url defaults to the URL stored on the show; a request already pending for the same show and platform is refused. Follow it in GET /v1/integrations/status.

  • Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.
  • Requires "confirm": true; without it the API answers 409 confirmation_required with the exact preview.

SDKlistener.dataRequests.create()client.data_requests.create()

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • show_idstringrequired
    A show id in this workspace (see GET /v1/shows).
  • platformstringrequired
    A platform name (e.g. youtube, spotify, applePodcasts, instagram).
    One ofspotifyapplePodcasts
  • show_urlstringnullable
  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

  • confirmboolean
    Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.

    Default false

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error