Skip to content
Listener.comDevelopers

Quickstart

Create a key, make your first request and read your reach, in about two minutes.

2 min read

You need a Listener account with at least one show. Everything below works the same for a Listener creator account and a Listener Networks workspace.

  1. Create an API key

    Open Settings → Developers in the app you use:

    Choose Create key, give it a name you will recognise later (for example “Weekly reporting script”) and pick the Read preset. Copy the key when it is shown: it starts with lsk_ and is only displayed once.

    Warning:

    Treat the key like a password. Keep it on your server or in a secrets manager, never in a browser, a mobile app or a public repository. See Authentication.

  2. Make your first request

    Export the key, then ask the API who you are. GET /v1/me returns the workspace the key belongs to, its shows, data freshness and the key itself.

    Terminal
    export LISTENER_API_KEY="lsk_…"
    curl https://api.listener.com/v1/me \
  -H "Authorization: Bearer $LISTENER_API_KEY"

    A successful response looks like this (trimmed):

    200 OK
    {
  "object": "workspace",
  "kind": "network",
  "network_name": "Northwind Audio",
  "plan": "network",
  "show_count": 12,
  "shows": [
    {
      "id": "8sQe1v0x2kTq",
      "name": "Dugout Daily",
      "handle": "dugoutdaily",
      "connected_platforms": ["youtube", "spotify", "instagram"]
    }
  ],
  "stale_platforms": [],
  "credential": {
    "object": "credential",
    "type": "api_key",
    "label": "Weekly reporting script",
    "scopes": ["workspace:read"]
  }
}

    If you see 401 credential_invalid, the key was copied incompletely. Every error links to its explanation in Errors.

  3. List your shows

    Show ids are what most other endpoints take. Lists come back in a standard envelope with data, has_more and next_cursor (see Pagination).

    curl -G https://api.listener.com/v1/shows \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -d limit=10

  4. Read your reach

    GET /v1/analytics/reach returns the KPI cards from the Analytics page: total, youtube, audio, social and newsletter reach for a window, each with current, previous and growth. Leave out show_ids for the whole workspace, or pass a subset (repeat the parameter or comma-separate the ids).

    curl -G https://api.listener.com/v1/analytics/reach \
  -H "Authorization: Bearer $LISTENER_API_KEY" \
  -d time_range=30d

    Two fields deserve attention from day one:

    • growth is null when the previous window has less than half its days covered by data. Show it as a dash (—), never as 0. See Time windows.
    • freshness and stale_platforms tell you when a platform has not updated for more than 36 hours. A suspiciously low number is usually a stale connection, not a lost audience. See Data freshness.

Next steps#

AuthenticationScopes, key rotation and keeping credentials safe.API referenceEvery endpoint, with a Try it console.WebhooksGet notified instead of polling.Metrics glossaryWhat reach, EMV and CPM mean here.