{"openapi":"3.1.0","info":{"title":"Listener API","version":"2026-10-14","summary":"Podcast network analytics, clusters, campaigns and reports.","description":"One API for every Listener workspace (networks, subnetworks and solo shows). It reports the same numbers as the Listener apps and the Listener server.\n\nAuthenticate with `Authorization: Bearer lsk_…` (an API key) or an OAuth access token. Pin behaviour with `Listener-Version: 2026-10-14`. Writes accept `dry_run: true` (the test mode) and `Idempotency-Key`. Guides: https://developers.listener.com","contact":{"name":"Listener","url":"https://developers.listener.com"}},"servers":[{"url":"https://api.listener.com"}],"tags":[{"name":"Meta","description":"API root, the OpenAPI document and the calling credential's workspace."},{"name":"Workspace & shows","description":"The workspace (network, subnetwork or solo show), its shows, plan, team, integrations and public profiles."},{"name":"Episodes","description":"Episodes per show, search, transcripts, tags, goals and Substack download figures."},{"name":"Analytics","description":"Account-level reach, timelines, rankings, platform stats and recent content. These endpoints cost 2 rate-limit tokens."},{"name":"Clusters","description":"Episode clusters (an episode plus its clips and posts), cluster reports and timelines, and the AI cluster builder."},{"name":"Campaigns","description":"Sponsorship campaigns, slots, cluster links, brand profiles and air checks."},{"name":"Reports","description":"Shared reports, report templates and report automations."},{"name":"Sponsors","description":"Sponsor matching, network bundle opportunities and sponsorship packages."},{"name":"Library & research","description":"Workspace library files, web research, podcast search and insertion-order parsing."},{"name":"Refresh","description":"Metered actions: platform refreshes and Spotify / Apple data requests."},{"name":"Partner integrations","description":"For hosting and ad-tech partners: discover and connect a show's accounts, set its podcast identity, look up episodes by your own ids, control auto-build, and record ad-server delivery on campaigns."},{"name":"Webhooks & events","description":"Webhook endpoints, deliveries and the Events API."}],"paths":{"/v1":{"get":{"operationId":"get_api_root","summary":"API root","tags":["Meta"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Version, links and the docs URL. No authentication.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"api"},"version":{"type":"string"},"docs_url":{"type":"string"},"openapi_url":{"type":"string"},"links":{"type":"object"}}},"example":{"object":"api","name":"Listener API","version":"2026-10-14","versions":["2026-10-14"],"server_version":"2.5.0","docs_url":"https://developers.listener.com","openapi_url":"https://api.listener.com/v1/openapi.json","links":{"me":"https://api.listener.com/v1/me","shows":"https://api.listener.com/v1/shows","campaigns":"https://api.listener.com/v1/campaigns","event_types":"https://api.listener.com/v1/event-types","oauth_metadata":"https://api.listener.com/baseline-banter/oauth-authorization-server","mcp":"https://api.listener.com/mcp"}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[],"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1\");\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1\",\n)\nprint(resp.json())"}]}},"/v1/openapi.json":{"get":{"operationId":"get_openapi_document","summary":"OpenAPI document","tags":["Meta"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"This API as an OpenAPI 3.1 document. No authentication.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","description":"An OpenAPI 3.1 document."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[],"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/openapi.json\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/openapi.json\");\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/openapi.json\",\n)\nprint(resp.json())"}]}},"/v1/me":{"get":{"operationId":"get_me","summary":"Retrieve the workspace and credential","tags":["Meta"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The workspace this credential resolves to: identity, kind (`network`, `subnetwork` or `solo`), plan, every show (id, name, handle, public URL, categories, connected platforms), `missing_show_ids` (shows the workspace points at that no longer exist; excluded everywhere), team and subnetwork counts, integrations summary and per-platform data freshness, plus the calling `credential` (type, id, label, scopes, OAuth client).\n\nStart here: the show ids every other endpoint accepts come from this response or `GET /v1/shows`. Solo workspaces return one show; subnetworks report `parent_network_uid`.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"allOf":[{"$ref":"#/components/schemas/GetWorkspaceResult"},{"type":"object","properties":{"credential":{"$ref":"#/components/schemas/Credential"}}}]},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"workspace"}}}]},"example":{"object":"workspace","effective_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","authenticated_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","auth_kind":"api_key","key_label":"revamp-dev","scopes":["workspace:read","workspace:write"],"kind":"network","is_network":true,"is_subnetwork":false,"parent_network_uid":null,"network_name":"Northwind Audio","network_handle":"northwind-audio","network_logo":"https://images.example.com/listener/fdacdc5d7150ed7b.jpg","plan":"premium","shows":[{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court","categories":["Sports","Comedy"],"plan":"premium","connected_platforms":["applePodcasts","instagram"],"stale_platforms":["applePodcasts"],"episode_count":2242},{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen","categories":["Fantasy Sports","Sports News"],"plan":"premium","connected_platforms":["applePodcasts","instagram"],"stale_platforms":["applePodcasts","spotify"],"episode_count":1428}],"show_count":12,"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"team_size":1,"subnetwork_count":0,"campaign_count":21,"integrations_summary":{"applePodcasts":10,"facebook":1,"instagram":11,"instagramBusiness":1,"megaphone":3,"omnystudio":1,"spotify":12,"threads":3,"tiktok":11,"twitter":10,"youtube":7},"data_freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"network_default_emv":{"likeRate":0.25,"longFormCpm":25,"shortFormCpm":20,"commentRate":1.25},"public_url":"https://network.listener.com/northwind-audio","app_url":"https://network.listener.com/app/dashboard?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","computed_at":"2026-10-14T17:34:12.427723+00:00","cache_age_seconds":6.9,"note":"2 managedKits entries point at deleted shows; clean them in Listener Networks → Shows.","credential":{"object":"credential","type":"api_key","id":"jSmUlIkAtT5p","label":"revamp-dev","scopes":["workspace:read","workspace:write"],"client_id":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/me\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/me\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/me\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows":{"get":{"operationId":"list_shows","summary":"List shows","tags":["Workspace & shows"],"parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"include_hidden","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The workspace's shows with profile, plan, connected platforms and public URLs.\n\n`category` matches any of a show's categories (case-insensitive); `search` matches name, handle and description. Hidden shows (every category hidden on the profile) are left out unless `include_hidden=true`.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ShowRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"show"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/shows","data":[{"object":"show","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game","categories":["Sports","Basketball"],"plan":"premium","connected_platforms":["applePodcasts","instagram"],"stale_platforms":["applePodcasts","spotify"],"episode_count":2754,"description":"Highlights and analysis from the latest matchday.","author":"Northwind","hidden_categories":[],"is_hidden":false,"agency_managed":true,"created_at":"2025-09-01T17:22:29.493000+00:00","last_cluster_update":null,"host_names":["Morgan Diaz","Reese Carter"],"app_url":"https://network.listener.com/app/dashboard?uid=i3KlnFag2DgIpykraVxjrIZwJYcL"},{"object":"show","id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily","categories":["Technology","Sports"],"plan":"premium","connected_platforms":["applePodcasts","instagram"],"stale_platforms":["applePodcasts","spotify"],"episode_count":463,"description":"A deep dive into the numbers behind the season so far.","author":"Alex Rivera","hidden_categories":[],"is_hidden":false,"agency_managed":true,"created_at":"2025-09-01T17:33:30.709000+00:00","last_cluster_update":"2026-01-14T20:25:31.494600+00:00","host_names":["Alex Rivera"],"app_url":"https://network.listener.com/app/dashboard?uid=sLLP2LKo9LJHqRCtBjjWDsbyDImn"}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"filters":{"category":null,"search":null,"include_hidden":false},"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:12.430383+00:00","cache_age_seconds":6.9,"note":null,"total":12}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}":{"get":{"operationId":"get_show","summary":"Retrieve a show","tags":["Workspace & shows"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One show's full profile: hosts, categories, podcast metadata (RSS, Spotify and Apple ids), Spotify rating, sponsorship packages, past guests, collaborations, per-platform connection state and freshness, and public URLs.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetShowResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"show"}}}]},"example":{"object":"show","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","description":"Highlights and analysis from the latest matchday.","author":"Northwind","website":null,"categories":["Sports","Basketball"],"hidden_categories":[],"main_platform":"apple","plan":"premium","agency_managed":true,"created_by":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_at":"2025-09-01T17:22:29.493000+00:00","updated_at":"2026-04-13T17:28:59.370000+00:00","hosts":[{"id":null,"name":"Morgan Diaz","bio":"Clip from this week's episode. Full episode on YouTube and Spotify.","photo":"https://images.example.com/listener/09fdf85b7709cc3a.jpg","social_links":{"linkedin":"https://www.linkedin.com/in/mkaowcqjd/","tiktok":"https://www.tiktok.com/@matchday48","instagram":"https://www.instagram.com/tefxrxwfochj/","twitter":"https://x.com/tefxrxwfochj"}},{"id":null,"name":"Reese Carter","bio":"New episode out now. We break down the week's biggest storylines and answer your questions.","photo":"https://images.example.com/listener/b60b8d133c43b54b.jpg","social_links":{"linkedin":"https://www.linkedin.com/in/pautuls-jilygfhx-29282s7x/"}}],"show_host_section":true,"talent":[],"podcast_metadata":{"provider":null,"provider_id":null,"provider_url":null,"rss_url":null,"spotify_id":"2pGhC7Mvqu6L2VzmndqWLq","apple_podcasts_id":"0807847418","total_episodes":null,"average_episode_length_sec":null,"imported_at":null},"spotify_rating":{"rating":4.65,"total_ratings":954402,"total_episodes":2754},"platforms":[{"platform":"applePodcasts","connected":true,"has_data":true,"last_updated":"2026-04-13T17:28:59+00:00","importing_state":null,"freshness":{"last_updated":"2026-04-13T17:28:59+00:00","age_hours":4416.09,"stale":true}},{"platform":"beehiiv","connected":false,"has_data":false,"last_updated":null,"importing_state":null,"freshness":null}],"connected_platforms":["applePodcasts","instagram"],"freshness":{"youtube":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false},"spotify":{"last_updated":"2026-09-22T22:06:27.429000+00:00","age_hours":523.46,"stale":true},"applePodcasts":{"last_updated":"2026-04-13T17:28:59+00:00","age_hours":4416.09,"stale":true},"tiktok":{"last_updated":"2026-10-13T09:35:24.476000+00:00","age_hours":31.98,"stale":false},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"sponsorship_packages":[],"collaborations":[],"past_guests":[{"id":null,"name":"Rowan Blake","title":"Power rankings, week 6","bio":"A deep dive into the numbers behind the season so far.","photo":"https://images.example.com/listener/c3b2579e6356fc07.jpg","featured":false,"episode_link":"https://open.spotify.com/episode/74E9FEMUr1EzoWXQlDVN5C"},{"id":null,"name":"Sage Turner","title":"Playoff picture, explained","bio":"New episode out now. We break down the week's biggest storylines and answer your questions.","photo":"https://images.example.com/listener/d6d31a45da778191.jpg","featured":false,"episode_link":"https://open.spotify.com/episode/0wstKw9APFDUvHLk1VmhfS"}],"survey_data":null,"last_cluster_update":null,"last_update_stats":null,"episode_count":2754,"public_url":"https://listener.com/the-long-game","app_url":"https://network.listener.com/app/dashboard?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","computed_at":"2026-10-14T17:34:12.432340+00:00","cache_age_seconds":6.9}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"patch":{"operationId":"update_show_profile","summary":"Update a show's public profile","tags":["Workspace & shows"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Update public-profile fields shown on `https://listener.com/{handle}`: name, author, logo, about, categories (up to 5), main platform, featured YouTube video (URL or 11-character id), highlighted Spotify episode (URL or 22-character id), publishing schedule, brand colours (`#hex`) and website. Only the fields you send change.\n\nChanging `handle` needs `\"confirm\": true`: it is slugified, checked for uniqueness, and the old public URL stops resolving (nothing redirects). Custom stats, display settings, hosts, collaborations and email are never touched. The response is the exact update map.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `shows:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"podcast_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"podcast_author":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"podcast_logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"about":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Only shows whose categories contain one of these (case-insensitive substring)."},"main_platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"youtube_video":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"highlighted_episode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"publishing_schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"custom_schedule":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"primary_color":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"secondary_color":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Public URL handle (lowercase, hyphens)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"show","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/i3KlnFag2DgIpykraVxjrIZwJYcL","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","method":"transaction","written":{"profile.about":"API probe (dry run)","updatedAt":"2026-10-14T17:34:12.766Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/connect?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","public":"https://listener.com/the-long-game"},"error":null,"data":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/shows/SHOW_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/shows/SHOW_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/plan":{"get":{"operationId":"get_plan","summary":"Retrieve the plan","tags":["Workspace & shows"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The resolved plan (explicit plan → subscription → network → free) and the premium platforms and features it unlocks. Check it before offering an integration the plan locks.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetPlanResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"plan"}}}]},"example":{"object":"plan","plan":"premium","plan_source":"explicit","is_paid":true,"premium_platforms":["spotify","applePodcasts"],"locked_platforms":[],"gated_features":{"premium_audio_platforms":true,"campaigns":true,"subnetworks":true,"team_members":true,"shared_reports":true,"clusters":true,"network_public_page":true,"mcp_writes":false},"shows_plans":{"paAtKPJGo56md5VyoEQ9Las7qahL":"premium","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H":"premium","HTSVG2lSc1RmPELJNtCnvOEb4Z2u":"premium","Xl2xMNVBZpyUA7MVJpqcKkFhEM2X":"premium","i3KlnFag2DgIpykraVxjrIZwJYcL":"premium","p3KfMe4Kfe1mY1eWjLLGFzS2wtUu":"premium","sLLP2LKo9LJHqRCtBjjWDsbyDImn":"premium","PXjDgD84U0pDobe25GOpKoNGTT1i":"premium","jgDOYIsPG3c9Jk7mysodavhQxXhV":"premium","Of9Els0RskCtlyZFPG8ujblH3NKI":"premium","2RSfMoyvMja3bzIq9vdY0UeZ0Jp8":"premium","h2DMGe9hfktytWWa0ZxVj1jMQbUb":"premium"},"writes_enabled":true,"note":null,"computed_at":"2026-10-14T17:34:12.769014+00:00","cache_age_seconds":7.2}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/plan\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/plan\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/plan\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/team":{"get":{"operationId":"get_team","summary":"Retrieve the team","tags":["Workspace & shows"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The network team: accepted members, pending invites and talent invites per show. Emails are masked (`j***@domain`).\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetTeamResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"team"}}}]},"example":{"object":"team","owner_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","members":[],"pending_invites":[],"team_size":1,"talent_by_show":[{"show_id":"p3KfMe4Kfe1mY1eWjLLGFzS2wtUu","show_name":"Rink Rats","talent":[{"email":"d***@mxsxmlhkfvuhc15","uid":"64NBXKv1myJyv2r2Mu9d7fE7SDF4","status":"accepted","role":"talent","invited_at":"2025-11-26T13:59:41.004000+00:00","accepted_at":"2025-11-26T16:06:39.392000+00:00"}]},{"show_id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","show_name":"Dugout Daily","talent":[{"email":"b***@mxsxmlhkfvuhc15","uid":null,"status":"pending","role":"talent","invited_at":"2025-11-26T13:59:22.108000+00:00","accepted_at":null}]}],"note":null,"computed_at":"2026-10-14T17:34:12.770975+00:00","cache_age_seconds":7.2}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/team\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/team\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/team\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/subnetworks":{"get":{"operationId":"list_subnetworks","summary":"List subnetworks","tags":["Workspace & shows"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The network's subnetworks (id, name, handle, show ids, activation state, public URL). Never returns credentials. Solo workspaces get an empty list with `meta.note`; a subnetwork reports `parent_network_uid` instead.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SubnetworkSummary"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"subnetwork"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"total":{"title":"Total","type":"integer"},"is_subnetwork":{"default":false,"title":"Is Subnetwork","type":"boolean"},"parent_network_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Network Uid"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/subnetworks","data":[],"has_more":false,"next_cursor":null,"meta":{"total":0,"is_subnetwork":false,"parent_network_uid":null,"note":"No subnetworks configured.","computed_at":"2026-10-14T17:34:12.773152+00:00","cache_age_seconds":7.2}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/subnetworks\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/subnetworks\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/subnetworks\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/urls":{"get":{"operationId":"get_public_urls","summary":"Build public and app URLs","tags":["Workspace & shows"],"parameters":[{"name":"entity","in":"query","required":true,"schema":{"enum":["network","show","cluster","campaign","brand","report","chart","link"],"type":"string"}},{"name":"id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"show_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Build the public share URL and in-app URL for a `network`, `show`, `cluster`, `campaign`, `brand`, `report`, `chart` or `links` page. `id` is the entity id (cluster id, campaign id, brand slug, report id, chart id); `show_id` is required for show, cluster and links pages. The entity is not checked for existence.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetPublicUrlsResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"public_url"}}}]},"example":{"object":"public_url","entity":"network","id":null,"show_id":null,"public_url":"https://network.listener.com/northwind-audio","app_url":"https://network.listener.com/app/dashboard?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/urls?entity=ENTITY\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/urls?entity=ENTITY\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/urls?entity=ENTITY\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/network":{"patch":{"operationId":"update_network_profile","summary":"Update the network's public profile","tags":["Workspace & shows"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Update the network's public profile shown on `https://network.listener.com/{handle}`: name, owner, website, contact email, about, focus, categories (up to 5), founded year, layout and the AI / reach-stats toggles. Only the fields you send change.\n\nChanging `handle` (`^[a-z0-9-]+$`) needs `\"confirm\": true`; the old public URL stops resolving. Privacy, custom domain, brand colours and sponsors are never touched. Solo workspaces have no network profile (400).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `shows:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"network_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"network_owner":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"network_website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"about":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"main_focus":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Only shows whose categories contain one of these (case-insensitive substring)."},"founded_year":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"podcast_display_layout":{"anyOf":[{"enum":["grid","list"],"type":"string"},{"type":"null"}],"default":null},"show_ai":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"show_reach_stats":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Public URL handle (lowercase, hyphens)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"network","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78","id":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","method":"transaction","written":{"networkProfile.about":"API probe (dry run)","updatedAt":"2026-10-14T17:34:12.936Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/network-connect?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio"},"error":null,"data":{"network_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/network\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/network\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/network\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/network/default-emv":{"put":{"operationId":"set_network_default_emv","summary":"Set the network's default EMV rates","tags":["Workspace & shows"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set the network-wide default EMV rates inherited by every cluster and campaign without its own override. CPMs are dollars per 1,000 impressions; like and comment rates are dollars each; every value must be a finite number ≥ 0. Needs `\"confirm\": true` because it changes EMV figures across the whole workspace.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `shows:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"long_form_cpm":{"type":"number"},"short_form_cpm":{"type":"number"},"like_rate":{"type":"number"},"comment_rate":{"type":"number"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false,"required":["long_form_cpm","short_form_cpm","like_rate","comment_rate"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"network_default_emv","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78","id":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","method":"update","written":{"networkDefaultEmv":{"longFormCpm":25,"shortFormCpm":20,"likeRate":0.25,"commentRate":1.25},"updatedAt":"2026-10-14T17:34:13.090Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/dashboard?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":null},"error":null,"data":{"networkDefaultEmv":{"longFormCpm":25,"shortFormCpm":20,"likeRate":0.25,"commentRate":1.25},"confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/network/default-emv\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"long_form_cpm\": 1.0, \"short_form_cpm\": 1.0, \"like_rate\": 1.0, \"comment_rate\": 1.0, \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/network/default-emv\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"long_form_cpm\": 1.0, \"short_form_cpm\": 1.0, \"like_rate\": 1.0, \"comment_rate\": 1.0, \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/network/default-emv\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={   'long_form_cpm': 1.0,\n        'short_form_cpm': 1.0,\n        'like_rate': 1.0,\n        'comment_rate': 1.0,\n        'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/integrations":{"get":{"operationId":"list_integrations","summary":"List platform integrations","tags":["Workspace & shows"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"name":"state","in":"query","required":false,"schema":{"default":"all","enum":["all","connected","pending","disconnected"],"type":"string"}},{"name":"stale_only","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One row per show × platform (the 18 platforms of the Integrations page): connection state (`connected`, `pending`, `disconnected`), last update, staleness, how it can be refreshed (`server`, `manual_request`, `none`), whether a refresh needs `confirm`, and the last stored error.\n\n`platform` accepts aliases; `stale_only=true` keeps rows older than 36 h. For the per-show rollup with cluster freshness and pending data requests use `GET /v1/integrations/status`.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/IntegrationRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"integration"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/IntegrationsSummary"},"platforms":{"description":"The 18 platform keys the Integrations page tracks, in its Audio → Content order.","items":{"type":"string"},"title":"Platforms","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/integrations","data":[{"object":"integration","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"platform":"spotify","label":"Spotify","group":"audio","state":"connected","state_reason":"platformOrder.connected","connected_flag":false,"platform_order_connected":true,"has_data":true,"importing_state":null,"status":null,"setup_step":null,"disconnected_at":null,"last_updated":"2026-10-14T07:20:29.026000+00:00","age_hours":10.23,"stale":false,"refresh_kind":"manual_request","requires_confirm":false,"premium":true,"last_error":null},{"object":"integration","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"platform":"applePodcasts","label":"Apple Podcasts","group":"audio","state":"connected","state_reason":"platformOrder.connected","connected_flag":false,"platform_order_connected":true,"has_data":true,"importing_state":null,"status":null,"setup_step":null,"disconnected_at":null,"last_updated":"2026-04-13T17:36:30+00:00","age_hours":4415.96,"stale":true,"refresh_kind":"manual_request","requires_confirm":false,"premium":true,"last_error":null}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"summary":{"rows":216,"connected":66,"pending":0,"disconnected":150,"stale_connected":22,"by_platform":{"spotify":{"connected":10,"pending":0,"disconnected":2,"stale":9},"applePodcasts":{"connected":9,"pending":0,"disconnected":3,"stale":9},"simplecast":{"connected":0,"pending":0,"disconnected":12,"stale":0},"transistor":{"connected":0,"pending":0,"disconnected":12,"stale":0},"megaphone":{"connected":3,"pending":0,"disconnected":9,"stale":1},"art19":{"connected":0,"pending":0,"disconnected":12,"stale":0},"captivate":{"connected":0,"pending":0,"disconnected":12,"stale":0},"omnystudio":{"connected":1,"pending":0,"disconnected":11,"stale":0},"youtube":{"connected":7,"pending":0,"disconnected":5,"stale":1},"tiktok":{"connected":11,"pending":0,"disconnected":1,"stale":0},"instagram":{"connected":11,"pending":0,"disconnected":1,"stale":0},"linkedin":{"connected":0,"pending":0,"disconnected":12,"stale":0},"twitter":{"connected":10,"pending":0,"disconnected":2,"stale":1},"facebook":{"connected":1,"pending":0,"disconnected":11,"stale":1},"facebookGroups":{"connected":0,"pending":0,"disconnected":12,"stale":0},"beehiiv":{"connected":0,"pending":0,"disconnected":12,"stale":0},"substack":{"connected":0,"pending":0,"disconnected":12,"stale":0},"threads":{"connected":3,"pending":0,"disconnected":9,"stale":0}},"shows_with_any_connection":12,"shows_without_connections":0},"platforms":["spotify","applePodcasts"],"filters":{"show_ids":null,"platform":null,"state":"all","stale_only":false},"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:13.092101+00:00","cache_age_seconds":7.6,"note":null,"total":216}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/integrations\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/integrations\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/integrations\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/integrations/status":{"get":{"operationId":"get_refresh_status","summary":"Retrieve data freshness and refresh status","tags":["Workspace & shows"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"include_cluster_freshness","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Per show: the newest platform update, stale platforms grouped by how they can be refreshed, cluster refresh freshness (last run, failed nodes), pending Spotify / Apple data requests and the last cluster update stats. Check it before `POST /v1/shows/{show_id}/platforms/{platform}/refresh`, `POST /v1/data-requests` or a cluster refresh. `include_cluster_freshness=false` makes it cheaper.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetRefreshStatusResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"refresh_status"}}}]},"example":{"object":"refresh_status","shows":[{"show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"newest_platform_update":"2026-10-14T07:55:11.134000+00:00","newest_platform":"twitter","connected_platforms":["applePodcasts","instagram"],"platform_freshness":{"youtube":{"last_updated":"2026-10-14T07:52:53.974000+00:00","age_hours":9.69,"stale":false},"spotify":{"last_updated":"2026-10-14T07:20:29.026000+00:00","age_hours":10.23,"stale":false},"applePodcasts":{"last_updated":"2026-04-13T17:36:30+00:00","age_hours":4415.96,"stale":true},"tiktok":{"last_updated":"2026-10-14T07:54:34.140000+00:00","age_hours":9.66,"stale":false},"instagram":{"last_updated":"2026-10-14T07:54:18.265000+00:00","age_hours":9.67,"stale":false},"twitter":{"last_updated":"2026-10-14T07:55:11.134000+00:00","age_hours":9.65,"stale":false}},"stale_platforms":["applePodcasts"],"refreshable_stale_platforms":[],"request_only_stale_platforms":["applePodcasts"],"last_cluster_update":"2026-04-23T11:48:41.184246+00:00","last_update_stats":{"totalClusters":82,"successfulClusters":82,"updateTime":"2026-04-23T11:48:41.184254","totalNodes":1181,"failedClusters":0},"cluster_freshness":{"kind":"refreshed","at":"2026-10-08T05:55:29.001Z","last_refreshed_at":"2026-10-08T05:55:29.001Z","cluster_count":136,"failed_node_count":0,"clusters_with_errors":0,"errors":[]},"pending_data_requests":[],"recent_data_requests":[{"id":"JYTswSZxL67VDHhDwqiz","platform":"spotify","status":"completed","requested_at":"2025-10-27T13:51:08.683000+00:00","completed_at":null,"error":null},{"id":"kMe9DTY65xpovACV2nUr","platform":"applePodcasts","status":"completed","requested_at":"2025-10-23T15:29:50.389000+00:00","completed_at":null,"error":null}]},{"show":{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen"},"newest_platform_update":"2026-10-14T09:22:51.743000+00:00","newest_platform":"megaphone","connected_platforms":["applePodcasts","instagram"],"platform_freshness":{"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true},"spotify":{"last_updated":"2026-09-21T17:31:56.535000+00:00","age_hours":552.04,"stale":true},"applePodcasts":{"last_updated":"2026-09-20T17:42:50.074000+00:00","age_hours":575.86,"stale":true},"tiktok":{"last_updated":"2026-10-14T08:03:25.681000+00:00","age_hours":9.51,"stale":false},"instagram":{"last_updated":"2026-10-14T08:02:55.492000+00:00","age_hours":9.52,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"refreshable_stale_platforms":["twitter","youtube"],"request_only_stale_platforms":["applePodcasts","spotify"],"last_cluster_update":"2026-10-13T04:03:27.050175+00:00","last_update_stats":{"successfulClusters":4,"totalClusters":4,"updateTime":"2025-11-26T12:26:44.433295","totalNodes":7,"failedClusters":0},"cluster_freshness":{"kind":"saved","at":"2026-03-17T17:16:36.453Z","last_refreshed_at":null,"cluster_count":16,"failed_node_count":0,"clusters_with_errors":0,"errors":[]},"pending_data_requests":[],"recent_data_requests":[{"id":"PyGGBlSIoVnT4uQX20u7","platform":"spotify","status":"completed","requested_at":"2025-10-23T15:17:55.781000+00:00","completed_at":null,"error":null},{"id":"cQdGsxQmbl1zY2rcg3fQ","platform":"applePodcasts","status":"completed","requested_at":"2025-10-22T17:46:33.789000+00:00","completed_at":null,"error":null}]}],"stale_platforms":["applePodcasts","facebook"],"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"pending_request_count":0,"shows_with_stale_clusters":3,"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:13.108085+00:00","cache_age_seconds":7.6,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/integrations/status\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/integrations/status\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/integrations/status\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes":{"get":{"operationId":"list_episodes","summary":"List a show's episodes","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"all","enum":["all","30d","90d","quarter","year"],"type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"series","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Series tags. Repeat the parameter or comma-separate values."},{"name":"guests","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Guest tags. Repeat the parameter or comma-separate values."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Format tags. Repeat the parameter or comma-separate values."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Brand name or slug filter."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"has_cluster","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null}},{"name":"sort_by","in":"query","required":false,"schema":{"default":"date","enum":["date","total_reach","youtube_reach","audio_reach","social_reach","long_form_reach","short_form_reach","clips","posts","title"],"type":"string"},"description":"Sort field."},{"name":"sort_order","in":"query","required":false,"schema":{"default":"desc","enum":["asc","desc"],"type":"string"},"description":"asc or desc."},{"name":"view","in":"query","required":false,"schema":{"default":"simple","enum":["simple","goals","benchmark"],"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"A show's episodes as the Episodes page lists them: every episode the app knows (stored feed, Spotify chart, Apple and cluster-derived, newest first) with its cluster's reach by category and form, clips and posts, engagement, tags, brands, freshness and the cluster's public URL. `meta.episode_count` is the full count.\n\n`time_range` (`all`, `30d`, `90d`, `quarter`, `year`; or `start_date` + `end_date`) filters on the publish date; undated episodes never fall inside an active window. `series`, `guests` and `format` match episode tags (any-of). `has_cluster=true` keeps episodes whose cluster exists or has reach. `view=goals` adds per-episode target deltas from the show's episode goals; `view=benchmark` adds deltas against same-format peer medians (minimum 3 peers) and the ≥ 3× breakout badge.\n\n- Required scope: `episodes:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/EpisodeRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"episode"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"episode_count":{"description":"Size of the show's full episode universe before filters (stored episodes ∪ chart rows ∪ Apple ∪ cluster-derived).","title":"Episode Count","type":"integer"},"filtered_count":{"description":"Rows matching the filters (== page.total).","title":"Filtered Count","type":"integer"},"with_cluster_count":{"description":"Episodes in the universe with a source cluster.","title":"With Cluster Count","type":"integer"},"view":{"enum":["simple","goals","benchmark"],"title":"View","type":"string"},"date_range":{"additionalProperties":true,"title":"Date Range","type":"object"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"tag_options":{"additionalProperties":{"items":{"$ref":"#/components/schemas/TagOption"},"type":"array"},"title":"Tag Options","type":"object"},"brand_options":{"items":{"type":"string"},"title":"Brand Options","type":"array"},"goals":{"anyOf":[{"$ref":"#/components/schemas/GoalsSummary"},{"type":"null"}],"default":null},"benchmark":{"anyOf":[{"$ref":"#/components/schemas/BenchmarkSummary"},{"type":"null"}],"default":null},"cluster_freshness":{"$ref":"#/components/schemas/ShowRefreshFreshness"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/shows/i3KlnFag2DgIpykraVxjrIZwJYcL/episodes","data":[{"object":"episode","total_reach":1231,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":1231,"social_reach":0,"long_form_reach":1231,"short_form_reach":0,"long_form_count":1,"short_form_count":0,"clips":1,"posts":0,"total_engagement":0,"engagement_rate":0,"id":"2Uu4VPBZxmUSGm8pHYe9Cq","title":"Midseason awards","published_at":"2026-09-18","date_raw":"2026-09-18","duration":"01:10:12","duration_seconds":4212,"episode_number":null,"source_platform":"spotify","platform_label":"Spotify","is_manual":false,"is_external":true,"is_synthetic":false,"explicit":false,"cover":"https://images.example.com/listener/a3d3672df4e9ac70.jpg","share_url":"https://open.spotify.com/episode/2Uu4VPBZxmUSGm8pHYe9Cq","description":"The crew is back with rankings, hot takes and a listener mailbag.","tags":{"series":[],"format":[],"guests":[]},"brands":[],"cluster_id":"cluster-2Uu4VPBZxmUSGm8pHYe9Cq","has_cluster":true,"cluster_type":"episode","metrics_source":"nodes","summary_stale":false,"freshness":{"kind":"unknown","at":null,"source":null},"last_refreshed_at":null,"refresh_error_count":0,"cluster_public_url":"https://listener.com/cluster/i3KlnFag2DgIpykraVxjrIZwJYcL_cluster-2Uu4VPBZxmUSGm8pHYe9Cq","cluster_app_url":"https://network.listener.com/app/cluster?id=cluster-2Uu4VPBZxmUSGm8pHYe9Cq&uid=i3KlnFag2DgIpykraVxjrIZwJYcL","goals":null,"benchmark":null},{"object":"episode","total_reach":0,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"long_form_count":0,"short_form_count":0,"clips":0,"posts":0,"total_engagement":0,"engagement_rate":0,"id":"3yQkVZN18HajewTkZZtXqG","title":"Our bold predictions for the second half","published_at":"2026-09-17","date_raw":"2026-09-17","duration":null,"duration_seconds":null,"episode_number":null,"source_platform":"spotify","platform_label":"Spotify","is_manual":false,"is_external":false,"is_synthetic":false,"explicit":null,"cover":"https://images.example.com/listener/f7abb1fd9793951e.jpg","share_url":"https://open.spotify.com/episode/3yQkVZN18HajewTkZZtXqG","description":null,"tags":{"series":[],"format":[],"guests":[]},"brands":[],"cluster_id":null,"has_cluster":false,"cluster_type":null,"metrics_source":"none","summary_stale":false,"freshness":{"kind":"unknown","at":null,"source":null},"last_refreshed_at":null,"refresh_error_count":0,"cluster_public_url":null,"cluster_app_url":null,"goals":null,"benchmark":null}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"show":{"id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game"},"episode_count":349,"filtered_count":349,"with_cluster_count":1,"view":"simple","date_range":{"preset":"all","start":null,"end":null},"filters":{"series":null,"guests":null,"format":null,"brand":null,"search":null,"has_cluster":null,"sort_by":"date","sort_order":"desc"},"tag_options":{"series":[],"guests":[],"format":[]},"brand_options":[],"goals":null,"benchmark":null,"cluster_freshness":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"freshness":{"youtube":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false},"spotify":{"last_updated":"2026-09-22T22:06:27.429000+00:00","age_hours":523.46,"stale":true},"applePodcasts":{"last_updated":"2026-04-13T17:28:59+00:00","age_hours":4416.09,"stale":true},"tiktok":{"last_updated":"2026-10-13T09:35:24.476000+00:00","age_hours":31.98,"stale":false},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"missing_show_ids":[],"computed_at":"2026-10-14T17:34:13.311067+00:00","cache_age_seconds":7.8,"note":null,"total":349}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:read"]}],"x-required-scope":"episodes:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/episodes\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/{episode_id}":{"get":{"operationId":"get_episode","summary":"Retrieve an episode","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"path","required":true,"schema":{"type":"string"},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One episode: its episodes-table row (reach by category and form, clips and posts, engagement, tags, brands), stored Spotify / Apple / YouTube stats when present, a summary of its cluster (type, node counts, sponsor brands, linked campaigns, freshness), goal deltas and benchmark bucket. `episode_id` is any id `GET /v1/shows/{show_id}/episodes` or `GET /v1/episodes/search` returns (Spotify, `manual-<ts>`, Apple or synthetic ids).\n\n- Required scope: `episodes:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetEpisodeResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"episode"}}}]},"example":{"object":"episode","show":{"id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game"},"episode":{"total_reach":1231,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":1231,"social_reach":0,"long_form_reach":1231,"short_form_reach":0,"long_form_count":1,"short_form_count":0,"clips":1,"posts":0,"total_engagement":0,"engagement_rate":0,"id":"2Uu4VPBZxmUSGm8pHYe9Cq","title":"Midseason awards","published_at":"2026-09-18","date_raw":"2026-09-18","duration":"01:10:12","duration_seconds":4212,"episode_number":null,"source_platform":"spotify","platform_label":"Spotify","is_manual":false,"is_external":true,"is_synthetic":false,"explicit":false,"cover":"https://images.example.com/listener/a3d3672df4e9ac70.jpg","share_url":"https://open.spotify.com/episode/2Uu4VPBZxmUSGm8pHYe9Cq","description":"The crew is back with rankings, hot takes and a listener mailbag.","tags":{"series":[],"format":[],"guests":[]},"brands":[],"cluster_id":"cluster-2Uu4VPBZxmUSGm8pHYe9Cq","has_cluster":true,"cluster_type":"episode","metrics_source":"nodes","summary_stale":false,"freshness":{"kind":"unknown","at":null,"source":null},"last_refreshed_at":null,"refresh_error_count":0,"cluster_public_url":"https://listener.com/cluster/i3KlnFag2DgIpykraVxjrIZwJYcL_cluster-2Uu4VPBZxmUSGm8pHYe9Cq","cluster_app_url":"https://network.listener.com/app/cluster?id=cluster-2Uu4VPBZxmUSGm8pHYe9Cq&uid=i3KlnFag2DgIpykraVxjrIZwJYcL","goals":{"comparable":true,"targets":{"total_reach":null,"long_form_reach":null,"short_form_reach":null},"deltas":{"total_reach":null,"long_form_reach":null,"short_form_reach":null}},"benchmark":{"format":"long","year":2026,"quarter":3,"counts":{"long_form_count":1,"short_form_count":0},"periods":{"year":{"label":"2026","peer_count":0,"sufficient":false,"medians":{},"deltas":{},"median_counts":{}},"quarter":{"label":"Q3 2026","peer_count":0,"sufficient":false,"medians":{},"deltas":{},"median_counts":{}}},"breakout":null}},"sources":["index"],"spotify":{"plays":1231,"streams":1197,"audience_size":755},"apple":null,"youtube":null,"cluster":{"id":"cluster-2Uu4VPBZxmUSGm8pHYe9Cq","cluster_type":"episode","title":"Midseason awards","node_count":2,"clips":1,"posts":0,"episode_ids":["2Uu4VPBZxmUSGm8pHYe9Cq"],"sponsor_brands":[],"linked_campaign_ids":[],"linked_campaigns":[],"freshness":{"kind":"unknown","at":null,"source":null},"refresh_error_count":0,"refresh_errors":[],"metrics_source":"nodes","summary_stale":false,"public_url":"https://listener.com/cluster/i3KlnFag2DgIpykraVxjrIZwJYcL_cluster-2Uu4VPBZxmUSGm8pHYe9Cq","app_url":"https://network.listener.com/app/cluster?id=cluster-2Uu4VPBZxmUSGm8pHYe9Cq&uid=i3KlnFag2DgIpykraVxjrIZwJYcL"},"goals":{"targets":{"total_reach":null,"long_form_reach":null,"short_form_reach":null},"sources":{"total_reach":null,"long_form_reach":null,"short_form_reach":null},"series":null,"has_series_overrides":false,"has_any":false,"comparable_count":1},"benchmark":{"population_size":1,"years":[2026],"median_metrics":null,"breakout_count":0},"freshness":{"youtube":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false},"spotify":{"last_updated":"2026-09-22T22:06:27.429000+00:00","age_hours":523.46,"stale":true},"applePodcasts":{"last_updated":"2026-04-13T17:28:59+00:00","age_hours":4416.09,"stale":true},"tiktok":{"last_updated":"2026-10-13T09:35:24.476000+00:00","age_hours":31.98,"stale":false},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"computed_at":"2026-10-14T17:34:13.314716+00:00","cache_age_seconds":7.8,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:read"]}],"x-required-scope":"episodes:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/{episode_id}/transcript":{"get":{"operationId":"get_episode_transcript","summary":"Retrieve an episode transcript","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"path","required":true,"schema":{"type":"string"},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The best text available for an episode. Listener stores no transcripts, so `status` is `description-fallback` (the episode description, up to 9,000 characters) or `missing`; transcript text saved on a linked campaign's air check is returned in `aircheck_excerpts`. Do not present the description as a transcript.\n\n- Required scope: `episodes:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetEpisodeTranscriptResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"episode_transcript"}}}]},"example":{"object":"episode_transcript","show":{"id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game"},"episode_id":"2Uu4VPBZxmUSGm8pHYe9Cq","title":"Midseason awards","published_at":"2026-09-18","status":"description-fallback","text":"The crew is back with rankings, hot takes and a listener mailbag.","truncated":false,"character_count":1091,"aircheck_excerpts":[],"share_url":"https://open.spotify.com/episode/2Uu4VPBZxmUSGm8pHYe9Cq","computed_at":"2026-10-14T17:34:13.317479+00:00","cache_age_seconds":7.8,"note":"Listener does not store episode transcripts; this is the episode description."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:read"]}],"x-required-scope":"episodes:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/transcript\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/transcript\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/transcript\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/episodes/search":{"get":{"operationId":"search_episodes","summary":"Search episodes","tags":["Episodes"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Search text."},{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"limit","in":"query","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Search episodes by title, description, episode number or date across the workspace's shows; each hit carries its show, reach fields and cluster id. Real feed episodes rank above manual and synthetic rows. Pass `show_ids` to keep it fast on large networks. Results are not paginated; `limit` caps them.\n\n- Required scope: `episodes:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SearchEpisodeRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"episode"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"query":{"title":"Query","type":"string"},"total_matches":{"title":"Total Matches","type":"integer"},"limit":{"title":"Limit","type":"integer"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"searched_episode_count":{"description":"Episodes scanned across the scoped shows.","title":"Searched Episode Count","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/episodes/search","data":[{"object":"episode","total_reach":0,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"long_form_count":0,"short_form_count":0,"clips":0,"posts":0,"total_engagement":0,"engagement_rate":0,"id":"6hTm2v2JOiy5gloMYD6jOU","title":"What the numbers really say","published_at":"2026-10-02","date_raw":"2026-10-02","duration":"45:00","duration_seconds":2700,"episode_number":null,"source_platform":"spotify","platform_label":null,"is_manual":false,"is_external":false,"is_synthetic":false,"explicit":false,"cover":"https://images.example.com/listener/9ce451d729b585a9.jpg","share_url":"https://open.spotify.com/episode/6hTm2v2JOiy5gloMYD6jOU","description":"Clip from this week's episode. Full episode on YouTube and Spotify.","tags":{"series":[],"format":[],"guests":[]},"brands":[],"cluster_id":null,"has_cluster":false,"cluster_type":null,"metrics_source":"none","summary_stale":false,"freshness":{"kind":"unknown","at":null,"source":null},"last_refreshed_at":null,"refresh_error_count":0,"cluster_public_url":null,"cluster_app_url":null,"goals":null,"benchmark":null,"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"search_score":12.0},{"object":"episode","total_reach":0,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"long_form_count":0,"short_form_count":0,"clips":0,"posts":0,"total_engagement":0,"engagement_rate":0,"id":"7P8qBzsz5VhK7Aor1UFnrN","title":"Power rankings, week 6","published_at":"2026-10-01","date_raw":"2026-10-01","duration":"44:37","duration_seconds":2677,"episode_number":null,"source_platform":"spotify","platform_label":null,"is_manual":false,"is_external":false,"is_synthetic":false,"explicit":false,"cover":"https://images.example.com/listener/efd8cb77345c1231.jpg","share_url":"https://open.spotify.com/episode/7P8qBzsz5VhK7Aor1UFnrN","description":"New episode out now. We break down the week's biggest storylines and answer your questions.","tags":{"series":[],"format":[],"guests":[]},"brands":[],"cluster_id":null,"has_cluster":false,"cluster_type":null,"metrics_source":"none","summary_stale":false,"freshness":{"kind":"unknown","at":null,"source":null},"last_refreshed_at":null,"refresh_error_count":0,"cluster_public_url":null,"cluster_app_url":null,"goals":null,"benchmark":null,"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"search_score":12.0}],"has_more":false,"next_cursor":null,"meta":{"query":"the","total_matches":4082,"limit":3,"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"searched_episode_count":9135,"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:13.319053+00:00","cache_age_seconds":7.8,"note":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:read"]}],"x-required-scope":"episodes:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/episodes/search?query=QUERY\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/episodes/search?query=QUERY\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/episodes/search?query=QUERY\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/tags":{"post":{"operationId":"set_episode_tags","summary":"Set episode tags","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set episode tags (`series`, `format`, `guests`) on one or more episodes of a show. `mode=replace` overwrites every dimension you send (omitted dimensions become empty); `add` unions and `remove` subtracts only the dimensions you send. Values are trimmed and de-duplicated case-insensitively.\n\nAny id the episodes list returns is accepted; episodes known only from provider data or clusters are added to the stored list (`data.appended`), unknown ids come back in `data.not_found`. Cluster node tags are a separate system (`POST /v1/shows/{show_id}/clusters/{cluster_id}/nodes/tags`).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `episodes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"episode_ids":{"items":{"type":"string"},"maxItems":500,"minItems":1,"type":"array","description":"Episode ids on the show."},"series":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Series tags."},"format":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Format tags."},"guests":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Guest tags."},"mode":{"default":"replace","enum":["replace","add","remove"],"type":"string","description":"How the change applies (see the operation description)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["episode_ids"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"episode_tags","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/i3KlnFag2DgIpykraVxjrIZwJYcL","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","method":"transaction","written":{"spotify.episodes":"<1 episodes, 1 patched>","patched":{"2Uu4VPBZxmUSGm8pHYe9Cq":{"series":["API probe"]}}},"warnings":["1 episode(s) were only known from provider caches or clusters and were added to the stored episodes with their tags: 2Uu4VPBZxmUSGm8pHYe9Cq."],"urls":{"app":"https://network.listener.com/app/episodes?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","public":null},"error":null,"data":{"updated":["2Uu4VPBZxmUSGm8pHYe9Cq"],"appended":["2Uu4VPBZxmUSGm8pHYe9Cq"],"not_found":[],"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","tags_by_episode":{"2Uu4VPBZxmUSGm8pHYe9Cq":{"series":["API probe"]}},"doc_bytes_after":440946},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:write"]}],"x-required-scope":"episodes:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/episodes/tags\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"episode_ids\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/tags\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"episode_ids\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/tags\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'episode_ids': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episode-goals":{"put":{"operationId":"set_episode_goals","summary":"Set episode goals","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set the show's episode reach goals: a `default` target plus per-series overrides in `by_series` (keyed by series tag). Targets accept integers or shorthand (`\"250k\"`, `\"1.2M\"`); only positive values are kept. `clear=true`, or no positive target at all, removes the goals.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `episodes:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"default":{"anyOf":[{"$ref":"#/components/schemas/GoalTargets2"},{"type":"null"}],"default":null},"by_series":{"anyOf":[{"additionalProperties":{"$ref":"#/components/schemas/GoalTargets2"},"type":"object"},{"type":"null"}],"default":null},"clear":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"episode_goals","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/i3KlnFag2DgIpykraVxjrIZwJYcL","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","method":"update","written":{"profile.episodeGoals":{"version":1,"default":{"totalReach":250000},"bySeries":{}}},"warnings":[],"urls":{"app":"https://network.listener.com/app/episodes?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","public":null},"error":null,"data":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","goals":{"version":1,"default":{"totalReach":250000},"bySeries":{}},"cleared":false},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:write"]}],"x-required-scope":"episodes:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/shows/SHOW_ID/episode-goals\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episode-goals\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episode-goals\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/substack/downloads":{"put":{"operationId":"set_substack_podcast_downloads","summary":"Set Substack podcast downloads for an episode node","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set the podcast downloads on one Substack card by hand (the app's \"Edit metrics\"), or remove that override with `clear=true`. The figure is stored beside Substack's API count, counts in the cluster's audio reach and wins over an imported figure until cleared. `node_id` is a Substack post node from `GET /v1/shows/{show_id}/clusters/{cluster_id}` (its `podcast_downloads_source` is `manual`, `export` or `api`). For many episodes at once use `POST /v1/shows/{show_id}/substack/imports`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `episodes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cluster_id":{"type":"string","description":"Cluster id (see GET /v1/clusters)."},"node_id":{"type":"string","description":"Cluster node id."},"downloads":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null},"clear":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["cluster_id","node_id"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"substack_downloads","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"transaction","written":{"nodes[post-substack-1].data.podcastDownloadsManual":18250,"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":null,"public":null},"error":null,"data":{"node_id":"post-substack-1","before":{"downloads":12400,"source":"api"},"after":{"downloads":18250,"source":"manual"}},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:write"]}],"x-required-scope":"episodes:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/shows/SHOW_ID/substack/downloads\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"cluster_id\": \"CLUSTER_ID\", \"node_id\": \"NODE_ID\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/substack/downloads\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"cluster_id\": \"CLUSTER_ID\", \"node_id\": \"NODE_ID\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/shows/SHOW_ID/substack/downloads\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'cluster_id': 'CLUSTER_ID', 'node_id': 'NODE_ID', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/substack/imports":{"post":{"operationId":"import_substack_episode_stats","summary":"Import Substack episode stats (CSV)","tags":["Episodes"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Import Substack's podcast \"episode stats\" CSV for a show: each row's `Total` becomes the downloads on that episode's Substack cards (source `export`) and in cluster audio reach. Substack's API only reports the downloads Substack tracks itself (often ~70 % of the export), so this brings in the publisher's full figure.\n\n`csv_text` is the whole exported file (columns Title, Date, Downloads (first 30d), Total, …); rows match posts on publish time to the second, then title. Re-importing is safe. Hand-set figures still win. Send it with `\"dry_run\": true` first and review each cluster's before → after.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `episodes:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv_text":{"type":"string"},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["csv_text"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"substack_import","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters","id":"clusters","method":"batch","written":{"rows":2},"warnings":[],"urls":{"app":null,"public":null},"error":null,"data":{"rows_total":2,"rows_matched":1,"unmatched_rows":[{"title":"Mailbag: your questions answered","date":"2026-09-30"}],"clusters":[{"cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","audio_before":12400,"audio_after":18250}]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:write"]}],"x-required-scope":"episodes:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/substack/imports\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"csv_text\": \"CSV_TEXT\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/substack/imports\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"csv_text\": \"CSV_TEXT\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/substack/imports\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'csv_text': 'CSV_TEXT', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/analytics/reach":{"get":{"operationId":"get_reach_summary","summary":"Reach summary","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"social_count_mode","in":"query","required":false,"schema":{"default":"all","enum":["all","unique"],"type":"string"},"description":"all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only)."},{"name":"metric","in":"query","required":false,"schema":{"default":"reach","enum":["reach","engagement"],"type":"string"},"description":"Which measure to report."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n`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`.\n\n**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`.\n\n**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`).\n\n**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.\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetReachSummaryResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"reach_summary"}}}]},"example":{"object":"reach_summary","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","metric":"reach"},"computed_at":"2026-10-14T17:34:15.706382+00:00","cache_age_seconds":10.2,"note":null,"metric":"reach","social_count_mode":"all","total":{"current":35840243,"previous":77122707,"growth":-53.53,"platforms":["youtube","instagram"]},"youtube":{"current":1699627,"previous":2680728,"growth":-36.6,"platforms":["youtube"]},"audio":{"current":356022,"previous":1744915,"growth":-79.6,"platforms":["spotify","applePodcasts"]},"social":{"current":33784594,"previous":72697064,"growth":-53.53,"platforms":["instagram","tiktok"]},"newsletter":{"current":0,"previous":0,"growth":null,"platforms":["beehiiv","substack"]},"per_platform":{"youtube":1699627,"instagram":7666139,"tiktok":2015820,"twitter":24102635,"spotify":291087,"applePodcasts":590,"megaphone":1288,"omnystudio":63057},"previous_per_platform":{"youtube":2680728,"instagram":14725796,"tiktok":1902422,"twitter":56068846,"spotify":1719177,"applePodcasts":2859,"megaphone":662,"omnystudio":22217},"suppressed_platforms_by_show":{},"shows_in_totals":12}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/reach\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/reach\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/reach\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/timeline":{"get":{"operationId":"get_reach_timeline","summary":"Reach timeline","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"social_count_mode","in":"query","required":false,"schema":{"default":"all","enum":["all","unique"],"type":"string"},"description":"all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only)."},{"name":"metric","in":"query","required":false,"schema":{"default":"reach","enum":["reach","engagement"],"type":"string"},"description":"Which measure to report."},{"name":"chart_type","in":"query","required":false,"schema":{"default":"daily","enum":["daily","cumulative"],"type":"string"},"description":"daily values or a cumulative running total."},{"name":"include_previous","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Also return the previous period's series."},{"name":"include_per_show","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Also return a per-show breakdown."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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).\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetReachTimelineResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"reach_timeline"}}}]},"example":{"object":"reach_timeline","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","metric":"reach","chart_type":"daily"},"computed_at":"2026-10-14T17:34:15.741276+00:00","cache_age_seconds":10.2,"note":null,"metric":"reach","chart_type":"daily","social_count_mode":"all","rows":[{"date":"2026-09-15","total":1546364,"per_platform":{"youtube":77798,"instagram":429254,"twitter":978959,"spotify":60159,"applePodcasts":172,"megaphone":22},"cumulative":1546364},{"date":"2026-09-16","total":9046826,"per_platform":{"youtube":44948,"instagram":2062817,"tiktok":23419,"twitter":6858164,"spotify":57298,"applePodcasts":170,"megaphone":10},"cumulative":10593190}],"previous_rows":null,"total":35840243,"previous_total":77122707,"growth":-53.53,"per_platform":{"youtube":1699627,"instagram":7666139,"tiktok":2015820,"twitter":24102635,"spotify":291087,"applePodcasts":590,"megaphone":1288,"omnystudio":63057},"previous_per_platform":{"youtube":2680728,"instagram":14725796,"tiktok":1902422,"twitter":56068846,"spotify":1719177,"applePodcasts":2859,"megaphone":662,"omnystudio":22217},"peak_day":{"date":"2026-09-16","total":9046826,"per_platform":{"youtube":44948,"instagram":2062817,"tiktok":23419,"twitter":6858164,"spotify":57298,"applePodcasts":170,"megaphone":10},"cumulative":10593190},"per_show":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/timeline\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/timeline\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/timeline\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/shows":{"get":{"operationId":"get_shows_ranking","summary":"Rank shows","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"sort_by","in":"query","required":false,"schema":{"default":"total","enum":["total","youtube","audio","social","growth"],"type":"string"},"description":"Sort field."},{"name":"metric","in":"query","required":false,"schema":{"default":"reach","enum":["reach","engagement"],"type":"string"},"description":"Which measure to report."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ShowRankingRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"show_ranking"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"default":"reach","enum":["reach","engagement"],"title":"Metric","type":"string"},"sort_by":{"enum":["total","youtube","audio","social","growth"],"title":"Sort By","type":"string"},"total":{"description":"Sum of the rows' totals (never deduped, so it can exceed `GET /v1/analytics/reach` in unique mode).","title":"Total","type":"integer"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/analytics/shows","data":[{"object":"show_ranking","rank":1,"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"total":26429121,"youtube":0,"audio":95919,"social":26333202,"newsletter":0,"per_platform":{"instagram":5795481,"tiktok":1647271,"twitter":18890450,"spotify":95919},"previous_total":14404411,"previous_youtube":0,"previous_audio":366600,"previous_social":14037811,"growth":83.48,"days_with_data":22,"previous_days_with_data":30},{"object":"show_ranking","rank":2,"show":{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","handle":"the-overtime-report","image":"https://images.example.com/listener/498a319e58218172.jpg","public_url":"https://listener.com/the-overtime-report"},"total":5006355,"youtube":0,"audio":29011,"social":4977344,"newsletter":0,"per_platform":{"instagram":157261,"tiktok":125036,"twitter":4695047,"spotify":29011},"previous_total":48968093,"previous_youtube":0,"previous_audio":451437,"previous_social":48516656,"growth":-89.78,"days_with_data":17,"previous_days_with_data":30}],"has_more":false,"next_cursor":null,"meta":{"window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","metric":"reach","sort_by":"total","page":{"total":12,"limit":2,"offset":0,"has_more":true,"next_offset":2}},"computed_at":"2026-10-14T17:34:15.767685+00:00","cache_age_seconds":10.2,"note":null,"metric":"reach","sort_by":"total","total":35840243}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/shows\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/shows\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/shows\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/compare":{"get":{"operationId":"compare_shows","summary":"Compare two shows","tags":["Analytics"],"parameters":[{"name":"show_id_a","in":"query","required":true,"schema":{"type":"string"}},{"name":"show_id_b","in":"query","required":true,"schema":{"type":"string"}},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"metric","in":"query","required":false,"schema":{"default":"reach","enum":["reach","engagement"],"type":"string"},"description":"Which measure to report."},{"name":"include_series","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CompareShowsResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"show_comparison"}}}]},"example":{"object":"show_comparison","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2023-08-09","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":26,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"spotify":{"last_updated":"2026-09-22T22:06:27.429000+00:00","age_hours":523.46,"stale":true},"tiktok":{"last_updated":"2026-10-13T09:35:24.476000+00:00","age_hours":31.98,"stale":false},"twitter":{"last_updated":"2026-10-13T09:38:16.251000+00:00","age_hours":31.93,"stale":false},"youtube":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"show_ids":["i3KlnFag2DgIpykraVxjrIZwJYcL","sLLP2LKo9LJHqRCtBjjWDsbyDImn"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":["i3KlnFag2DgIpykraVxjrIZwJYcL","sLLP2LKo9LJHqRCtBjjWDsbyDImn"],"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","metric":"reach","include_series":false},"computed_at":"2026-10-14T17:34:15.788966+00:00","cache_age_seconds":10.3,"note":null,"metric":"reach","a":{"show":{"id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game"},"total":228083,"youtube":125564,"audio":4440,"social":98079,"newsletter":0,"per_platform":{"youtube":125564,"instagram":94198,"tiktok":3881,"spotify":4440},"previous_total":215711,"previous_youtube":132029,"previous_audio":29513,"previous_social":54169,"previous_per_platform":{"youtube":132029,"instagram":30046,"tiktok":24123,"spotify":29513},"growth":5.74,"days_with_data":26,"series":null},"b":{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"total":26429121,"youtube":0,"audio":95919,"social":26333202,"newsletter":0,"per_platform":{"instagram":5795481,"tiktok":1647271,"twitter":18890450,"spotify":95919},"previous_total":14404411,"previous_youtube":0,"previous_audio":366600,"previous_social":14037811,"previous_per_platform":{"instagram":6577322,"tiktok":710823,"twitter":6749666,"spotify":366600},"growth":83.48,"days_with_data":22,"series":null},"head_to_head":[{"metric":"total","a":228083.0,"b":26429121.0,"delta_a_minus_b":-26201038.0,"winner":"b"},{"metric":"youtube","a":125564.0,"b":0.0,"delta_a_minus_b":125564.0,"winner":"a"}],"overall_winner":"b"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/compare?show_id_a=SHOW_ID_A&show_id_b=SHOW_ID_B\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/compare?show_id_a=SHOW_ID_A&show_id_b=SHOW_ID_B\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/compare?show_id_a=SHOW_ID_A&show_id_b=SHOW_ID_B\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/distribution":{"get":{"operationId":"get_platform_distribution","summary":"Platform distribution","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"social_count_mode","in":"query","required":false,"schema":{"default":"all","enum":["all","unique"],"type":"string"},"description":"all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only)."},{"name":"metric","in":"query","required":false,"schema":{"default":"views","enum":["views","followers","engagement"],"type":"string"},"description":"Which measure to report."},{"name":"include_zero","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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).\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetPlatformDistributionResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"platform_distribution"}}}]},"example":{"object":"platform_distribution","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","metric":"views","include_zero":false},"computed_at":"2026-10-14T17:34:15.794047+00:00","cache_age_seconds":10.3,"note":null,"metric":"views","social_count_mode":"all","entries":[{"platform":"twitter","label":"X (Twitter)","value":24102635,"share":67.25},{"platform":"instagram","label":"Instagram","value":7666139,"share":21.39}],"total":35840243,"source":"daily performance (reach) for the window"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/distribution\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/distribution\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/distribution\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/dashboard":{"get":{"operationId":"get_dashboard_kpis","summary":"Dashboard KPIs","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"social_count_mode","in":"query","required":false,"schema":{"default":"all","enum":["all","unique"],"type":"string"},"description":"all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","enum":["7d","30d","90d"],"type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"table_mode","in":"query","required":false,"schema":{"default":"reach","enum":["reach","audience","demographics"],"type":"string"}},{"name":"top_content_per_platform","in":"query","required":false,"schema":{"default":3,"maximum":10,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n`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).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetDashboardKpisResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"dashboard"}}}]},"example":{"object":"dashboard","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.94,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","table_mode":"reach"},"computed_at":"2026-10-14T17:34:15.812876+00:00","cache_age_seconds":10.3,"note":null,"time_range":"30d","table_mode":"reach","tiles":[{"key":"followers","label":"Followers","value":8037076.0,"previous":null,"growth":null,"unit":"count","source":"live follower counts (deliberately disconnected platforms zeroed)","window":"live"},{"key":"impressions","label":"Impressions","value":35840243.0,"previous":77122707.0,"growth":-53.53,"unit":"count","source":"daily performance total (reach)","window":"30d"}],"emv":{"total":898024.97,"audio_value":8900.55,"social_value":709684.42,"like_value":155665.0,"comment_value":23775.0,"audio_downloads":356022,"social_impressions":35484221,"likes":622660,"comments":19020,"rates":{"long_form_cpm":25.0,"short_form_cpm":20.0,"like_rate":0.25,"comment_rate":1.25},"rates_source":"network_default","formula":"audio_downloads × long_form_cpm / 1000 + (impressions − audio_downloads) × short_form_cpm / 1000 + likes × like_rate + comments × comment_rate"},"per_platform_reach":{"youtube":1699627,"instagram":7666139,"tiktok":2015820,"twitter":24102635,"spotify":291087,"applePodcasts":590,"megaphone":1288,"omnystudio":63057},"shows":[{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"total":26429121,"youtube":0,"audio":95919,"social":26333202,"growth":83.48,"followers":null,"followers_by_platform":null,"demographics":null,"connected_platforms":["applePodcasts","instagram"]},{"show":{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","handle":"the-overtime-report","image":"https://images.example.com/listener/498a319e58218172.jpg","public_url":"https://listener.com/the-overtime-report"},"total":5006355,"youtube":0,"audio":29011,"social":4977344,"growth":-89.78,"followers":null,"followers_by_platform":null,"demographics":null,"connected_platforms":["applePodcasts","instagram"]}],"top_content":{"instagram":[{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"instagram","post_type":"reel","id":"SjNbswoa1F2","date":"2026-09-16T16:18:13+00:00","url":"https://www.instagram.com/reel/SjNbswoa1F2/","title":null,"caption":"Our hosts react to the weekend's results and look ahead to next week.","metrics":{"plays":1792324,"likes":91485,"comments":2011,"shares":0,"saves":0,"engagement":93496},"primary_metric":"plays","primary_value":1792324.0},{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"instagram","post_type":"reel","id":"DeKyFsSy-Gd","date":"2026-10-06T21:47:23+00:00","url":"https://www.instagram.com/reel/SrFsSoGl-Ox/","title":null,"caption":"A deep dive into the numbers behind the season so far.","metrics":{"plays":1032660,"likes":56838,"comments":1176,"shares":0,"saves":0,"engagement":58014},"primary_metric":"plays","primary_value":1032660.0}],"tiktok":[{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"tiktok","post_type":"video","id":null,"date":"2026-10-06T14:51:11+00:00","url":"https://www.tiktok.com/@northwindaudio/video/5393438153226530115","title":null,"caption":"New episode out now. We break down the week's biggest storylines and answer your questions.","metrics":{"plays":759965,"likes":35992,"comments":1145,"shares":8173,"engagement":45310},"primary_metric":"plays","primary_value":759965.0},{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"tiktok","post_type":"video","id":null,"date":"2026-09-24T20:37:21+00:00","url":"https://www.tiktok.com/@northwindaudio/video/5933203068549452749","title":null,"caption":"Clip from this week's episode. Full episode on YouTube and Spotify.","metrics":{"plays":259315,"likes":16347,"comments":744,"shares":3361,"engagement":20452},"primary_metric":"plays","primary_value":259315.0}],"twitter":[{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"twitter","post_type":"tweet","id":"7831648775074218402","date":"2026-09-16T16:15:08+00:00","url":"https://x.com/hljglnultbysm/status/7831648775074218402","title":null,"caption":"Our hosts react to the weekend's results and look ahead to next week.","metrics":{"impressions":6068598,"likes":16837,"retweets":1567,"replies":316,"quotes":385,"engagement":19105},"primary_metric":"impressions","primary_value":6068598.0},{"show":{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"},"platform":"twitter","post_type":"tweet","id":"2499797339557722654","date":"2026-09-24T12:10:10+00:00","url":"https://x.com/hljglnultbysm/status/2499797339557722654","title":null,"caption":"A deep dive into the numbers behind the season so far.","metrics":{"impressions":2639906,"likes":10883,"retweets":1525,"replies":592,"quotes":484,"engagement":13484},"primary_metric":"impressions","primary_value":2639906.0}],"threads":[{"show":{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","handle":"the-overtime-report","image":"https://images.example.com/listener/498a319e58218172.jpg","public_url":"https://listener.com/the-overtime-report"},"platform":"threads","post_type":"post","id":null,"date":"2026-09-20T18:26:02+00:00","url":null,"title":null,"caption":"Clip from this week's episode. Full episode on YouTube and Spotify.","metrics":{"likes":2,"replies":0,"reposts":0,"quotes":0,"views":0},"primary_metric":"likes","primary_value":2.0}],"youtube":[{"show":{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen"},"platform":"youtube","post_type":"video","id":null,"date":"2026-09-26T15:00:02+00:00","url":null,"title":"The best and worst contracts","caption":"Our hosts react to the weekend's results and look ahead to next week.","metrics":{"views":56369,"likes":652,"comments":60},"primary_metric":"views","primary_value":56369.0},{"show":{"id":"PXjDgD84U0pDobe25GOpKoNGTT1i","name":"Baseline Banter","handle":"baseline-banter","image":"https://images.example.com/listener/b8cee59dda079226.jpg","public_url":"https://listener.com/baseline-banter"},"platform":"youtube","post_type":"video","id":null,"date":"2026-09-26T22:02:26+00:00","url":null,"title":"Trade deadline winners and losers","caption":"Highlights and analysis from the latest matchday.","metrics":{"views":47277,"likes":413,"comments":184},"primary_metric":"views","primary_value":47277.0}],"omnystudio":[{"show":{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen"},"platform":"omnystudio","post_type":"episode","id":"1635o053-p31z-6b13-xwp9-y9me44770cpq","date":"2026-09-27T07:00:00+00:00","url":null,"title":"What the numbers really say","caption":null,"metrics":{"downloads":8497},"primary_metric":"downloads","primary_value":8497.0},{"show":{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen"},"platform":"omnystudio","post_type":"episode","id":"u1d5m28e-g88g-8968-a85y-g1k09323320l","date":"2026-09-20T07:00:00+00:00","url":null,"title":"Inside the locker room with a two-time champion","caption":null,"metrics":{"downloads":8032},"primary_metric":"downloads","primary_value":8032.0}]},"metric_windows":{"followers":"live","impressions":"30d","likes":"30d","comments":"30d","posts":"30d","engagement_rate":"30d","downloads":"30d","emv":"30d","top_content":"30d"}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/dashboard\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/dashboard\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/dashboard\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/hosts":{"get":{"operationId":"get_hosts_ranking","summary":"Rank hosts","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"sort_by","in":"query","required":false,"schema":{"default":"audience","enum":["audience","youtube","social","shows_reach","name"],"type":"string"},"description":"Sort field."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/HostRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"host_ranking"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"sort_by":{"enum":["audience","youtube","social","shows_reach","name"],"title":"Sort By","type":"string"},"total_hosts":{"title":"Total Hosts","type":"integer"},"total_audience":{"title":"Total Audience","type":"integer"},"youtube_audience":{"title":"Youtube Audience","type":"integer"},"social_audience":{"title":"Social Audience","type":"integer"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/analytics/hosts","data":[{"object":"host_ranking","rank":1,"name":"Alex Rivera","bio":"A deep dive into the numbers behind the season so far.","photo":"https://images.example.com/listener/d92b66b977c8790e.jpg","primary_link":"https://www.instagram.com/iehltzn/","social_links":{"instagram":"https://www.instagram.com/iehltzn/","twitter":"https://x.com/XwbncCkntl","linkedin":"https://www.linkedin.com/in/ttpiftmmqa/"},"audience_by_platform":{"instagram":72500,"twitter":209032,"linkedin":1090},"total_audience":282622,"youtube_audience":0,"social_audience":282622,"shows":[{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","handle":"dugout-daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","public_url":"https://listener.com/dugout-daily"}],"shows_reach":26429121},{"object":"host_ranking","rank":2,"name":"Jordan Lee","bio":"New episode out now. We break down the week's biggest storylines and answer your questions.","photo":"https://images.example.com/listener/243b51e0f3551ea6.jpg","primary_link":"https://www.instagram.com/tilcymz/","social_links":{"instagram":"https://www.instagram.com/tilcymz/","twitter":"https://x.com/tilcymz"},"audience_by_platform":{"instagram":5636,"twitter":123821},"total_audience":129457,"youtube_audience":0,"social_audience":129457,"shows":[{"id":"PXjDgD84U0pDobe25GOpKoNGTT1i","name":"Baseline Banter","handle":"baseline-banter","image":"https://images.example.com/listener/b8cee59dda079226.jpg","public_url":"https://listener.com/baseline-banter"}],"shows_reach":1131220}],"has_more":false,"next_cursor":null,"meta":{"window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"previous_window_coverage_days":30,"current_window_coverage_days":29,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.95,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","sort_by":"audience","search":null,"page":{"total":12,"limit":2,"offset":0,"has_more":true,"next_offset":2}},"computed_at":"2026-10-14T17:34:15.912700+00:00","cache_age_seconds":10.4,"note":null,"sort_by":"audience","total_hosts":12,"total_audience":645053,"youtube_audience":251,"social_audience":644802}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/hosts\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/hosts\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/hosts\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/accounts":{"get":{"operationId":"get_account_dedup_view","summary":"Shared-account (dedup) view","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetAccountDedupViewResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"account_dedup"}}}]},"example":{"object":"account_dedup","platforms_checked":["youtube","spotify"],"has_duplicates":true,"duplicate_platforms":["spotify","megaphone"],"groups":[{"group_key":"youtube:uctr-zjgq5cumahxam6xvx8c","platform":"youtube","platform_category":"youtube","account_key":"uctr-zjgq5cumahxam6xvx8c","account_label":"Hard Court","canonical_show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","canonical_show_name":"Hard Court","members":[{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_name":"Hard Court","show_handle":"hard-court","platform":"youtube","account_key":"uctr-zjgq5cumahxam6xvx8c","account_label":"Hard Court","profile_url":"https://youtube.com/channel/SPrh-SDQx4HYhJEqfL0dnD4j","last_updated":"2026-10-14T07:52:53.974000Z","data_quality":9.0}],"is_duplicate":false},{"group_key":"youtube:mh2bnlijjv7-8m4hle7qid2j","platform":"youtube","platform_category":"youtube","account_key":"mh2bnlijjv7-8m4hle7qid2j","account_label":"The Bullpen","canonical_show_id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","canonical_show_name":"The Bullpen","members":[{"show_id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","show_name":"The Bullpen","show_handle":"the-bullpen","platform":"youtube","account_key":"mh2bnlijjv7-8m4hle7qid2j","account_label":"The Bullpen","profile_url":"https://youtube.com/channel/TE0aUgJYJs8-7y8oBh6CPv3n","last_updated":"2026-10-02T10:37:33.857000Z","data_quality":9.0}],"is_duplicate":false}],"duplicate_groups":[{"group_key":"spotify:5angy0pobo1s6ghbqfrvzv","platform":"spotify","platform_category":"audio","account_key":"5angy0pobo1s6ghbqfrvzv","account_label":"Baseline Banter","canonical_show_id":"PXjDgD84U0pDobe25GOpKoNGTT1i","canonical_show_name":"Baseline Banter","members":[{"show_id":"PXjDgD84U0pDobe25GOpKoNGTT1i","show_name":"Baseline Banter","show_handle":"baseline-banter","platform":"spotify","account_key":"5angy0pobo1s6ghbqfrvzv","account_label":"Baseline Banter","profile_url":"https://open.spotify.com/show/2pGhC7Mvqu6L2VzmndqWLq","last_updated":"2026-09-22T22:46:03.191000Z","data_quality":8.0},{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","show_handle":"the-long-game","platform":"spotify","account_key":"5angy0pobo1s6ghbqfrvzv","account_label":"The Long Game","profile_url":"https://open.spotify.com/show/2pGhC7Mvqu6L2VzmndqWLq","last_updated":"2026-09-22T22:06:27.429000Z","data_quality":8.0}],"is_duplicate":true},{"group_key":"megaphone:874r0412-5iet-50q5-3178-6b8lo30uza90","platform":"megaphone","platform_category":"audio","account_key":"874r0412-5iet-50q5-3178-6b8lo30uza90","account_label":"The Red Zone","canonical_show_id":"h2DMGe9hfktytWWa0ZxVj1jMQbUb","canonical_show_name":"The Red Zone","members":[{"show_id":"h2DMGe9hfktytWWa0ZxVj1jMQbUb","show_name":"The Red Zone","show_handle":"the-red-zone","platform":"megaphone","account_key":"874r0412-5iet-50q5-3178-6b8lo30uza90","account_label":"The Red Zone","profile_url":"","last_updated":"2026-10-14T17:30:25.621000Z","data_quality":7.0},{"show_id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","show_name":"The Bullpen","show_handle":"the-bullpen","platform":"megaphone","account_key":"874r0412-5iet-50q5-3178-6b8lo30uza90","account_label":"The Bullpen","profile_url":"","last_updated":"2026-10-14T09:22:51.743000Z","data_quality":7.0}],"is_duplicate":true}],"suppressed":{"i3KlnFag2DgIpykraVxjrIZwJYcL":["spotify"],"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H":["megaphone"]},"applies_to":["overview_totals","timeline"],"never_applied_to":["shows_ranking","compare_shows"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:15.929156+00:00","cache_age_seconds":10.4,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/accounts\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/accounts\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/accounts\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/analytics/categories":{"get":{"operationId":"list_show_categories","summary":"List show categories","tags":["Analytics"],"parameters":[{"name":"include_placeholders","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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`.\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CategoryEntry"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"show_category"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"total":{"title":"Total","type":"integer"},"placeholders_dropped":{"default":0,"description":"'Category N' placeholders skipped, like the analytics page.","title":"Placeholders Dropped","type":"integer"},"uncategorised_show_ids":{"items":{"type":"string"},"title":"Uncategorised Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/analytics/categories","data":[{"object":"show_category","category":"Baseball","show_count":1,"show_ids":["HTSVG2lSc1RmPELJNtCnvOEb4Z2u"]},{"object":"show_category","category":"Basketball","show_count":1,"show_ids":["i3KlnFag2DgIpykraVxjrIZwJYcL"]}],"has_more":false,"next_cursor":null,"meta":{"total":18,"placeholders_dropped":0,"uncategorised_show_ids":[],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:15.933657+00:00","cache_age_seconds":10.4,"note":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/analytics/categories\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/analytics/categories\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/analytics/categories\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/platforms":{"get":{"operationId":"get_platform_stats","summary":"A show's platform stats","tags":["Analytics"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"platform","in":"query","required":false,"schema":{"default":"all","type":"string"},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","enum":["7d","30d","90d"],"type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"include_raw","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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.\n\nOn 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.\n\n**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.\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetPlatformStatsResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"platform_stats"}}}]},"example":{"object":"platform_stats","show":{"id":"i3KlnFag2DgIpykraVxjrIZwJYcL","name":"The Long Game","handle":"the-long-game","image":"https://images.example.com/listener/4b71276112f25fab.jpg","public_url":"https://listener.com/the-long-game"},"time_range":"30d","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"metric_windows":{"metrics":"30d"},"platforms":[{"platform":"youtube","label":"YouTube","connected":true,"has_data":true,"importing_state":null,"source":"platformMetrics.calculateYoutubeMetrics","metrics":{"lifetime_views":1665727,"views":125564,"watch_time":890845,"subscribers":7410,"subscribers_gained":302,"avg_view_duration":386,"views_growth":861.5867667330372,"watch_time_growth":0,"subscribers_growth":0,"subs_gained_growth":788.2352941176471,"avg_duration_growth":0,"shows_with_data":1},"audience":{"demographics":{"age":[{"category":"age65-","percentage":27.3},{"category":"age55-64","percentage":19.5}],"gender":[{"category":"male","percentage":61.4},{"category":"female","percentage":38.6}]},"geographic":[{"country":"US","watchTime":620132,"views":89911},{"country":"CA","watchTime":27683,"views":4085}],"states":[{"province":"US-CA","watchTime":110410,"views":12807},{"province":"US-NY","watchTime":45316,"views":5800}],"video_retention":[],"traffic_sources":[{"source":"Subscriber Feed","rawSource":"SUBSCRIBER","views":74134},{"source":"RELATED_VIDEO","rawSource":"RELATED_VIDEO","views":18220}]},"freshness":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false},"raw":null,"raw_truncated":false,"window_totals":null}],"requested_platform":"youtube","freshness":{"youtube":{"last_updated":"2026-10-13T09:34:22.044000+00:00","age_hours":32.0,"stale":false},"spotify":{"last_updated":"2026-09-22T22:06:27.429000+00:00","age_hours":523.46,"stale":true},"applePodcasts":{"last_updated":"2026-04-13T17:28:59+00:00","age_hours":4416.09,"stale":true},"tiktok":{"last_updated":"2026-10-13T09:35:24.476000+00:00","age_hours":31.98,"stale":false},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false}},"stale_platforms":["applePodcasts","spotify"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:15.934519+00:00","cache_age_seconds":10.4,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/platforms\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/platforms\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/platforms\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/content":{"get":{"operationId":"get_recent_posts","summary":"Recent posts and content","tags":["Analytics"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"social_count_mode","in":"query","required":false,"schema":{"default":"all","enum":["all","unique"],"type":"string"},"description":"all counts every show's accounts; unique counts an account shared by several shows once (totals, timelines, distributions only)."},{"name":"group_by","in":"query","required":false,"schema":{"default":"none","enum":["none","day","platform"],"type":"string"},"description":"Group the results by this field."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"limit_per_platform","in":"query","required":false,"schema":{"default":0,"maximum":500,"minimum":0,"type":"integer"}},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"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).\n\n**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`.\n\n**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`).\n\n- Costs 2 rate-limit tokens.\n- Required scope: `analytics:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PostRecord"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"post"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"group_by":{"enum":["none","day","platform"],"title":"Group By","type":"string"},"platforms":{"items":{"type":"string"},"title":"Platforms","type":"array"},"groups":{"anyOf":[{"items":{"$ref":"#/components/schemas/PostGroup"},"type":"array"},{"type":"null"}],"default":null,"title":"Groups"},"posts_by_platform":{"additionalProperties":{"type":"integer"},"description":"Counts before limit/offset.","title":"Posts By Platform","type":"object"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/content","data":[{"object":"post","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"platform":"instagram","post_type":"reel","id":"LvfmwCJJN9O","date":"2026-10-13T20:30:16+00:00","day":"2026-10-13","url":"https://www.instagram.com/reel/LvfmwCJJN9O/","thumbnail":"https://images.example.com/listener/aa3f151af787003a.jpg","title":null,"caption":"Highlights and analysis from the latest matchday.","metrics":{"plays":1216,"likes":11,"comments":0,"shares":0,"saves":0,"engagement":11}},{"object":"post","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"platform":"youtube","post_type":"video","id":null,"date":"2026-10-13T20:30:15+00:00","day":"2026-10-13","url":null,"thumbnail":"https://images.example.com/listener/ad1db58b84403df9.jpg","title":"The best and worst contracts","caption":"The crew is back with rankings, hot takes and a listener mailbag.","metrics":{"views":891,"likes":10,"comments":0}}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"coverage":{"start":null,"embedded_boundary":"2026-09-15","history_used":false,"previous_window_coverage_days":0,"current_window_coverage_days":0,"growth_basis":"total","growth_platforms":null,"warnings":[]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.95,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"filters":{"show_ids":null,"categories":null,"platforms":null,"social_count_mode":"all","time_range":"30d","group_by":"none","page":{"total":531,"limit":2,"offset":0,"has_more":true,"next_offset":2},"limit_per_platform":0},"computed_at":"2026-10-14T17:34:16.106371+00:00","cache_age_seconds":10.6,"note":null,"group_by":"none","platforms":["instagram","tiktok"],"groups":null,"posts_by_platform":{"instagram":138,"tiktok":79,"twitter":147,"threads":1,"youtube":152,"omnystudio":14},"total":531}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["analytics:read"]}],"x-required-scope":"analytics:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/content\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/content\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/content\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/clusters":{"get":{"operationId":"list_clusters","summary":"List clusters","tags":["Clusters"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"time_range","in":"query","required":false,"schema":{"default":"all","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"series","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Series tags. Repeat the parameter or comma-separate values."},{"name":"guests","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Guest tags. Repeat the parameter or comma-separate values."},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Format tags. Repeat the parameter or comma-separate values."},{"name":"custom_tags","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Repeat the parameter or comma-separate values."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Brand name or slug filter."},{"name":"state","in":"query","required":false,"schema":{"default":"all","enum":["all","active","empty","merged","manual"],"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"sort_by","in":"query","required":false,"schema":{"default":"published_at","enum":["published_at","total_reach","youtube_reach","audio_reach","social_reach","node_count","last_refreshed_at","name"],"type":"string"},"description":"Sort field."},{"name":"sort_order","in":"query","required":false,"schema":{"default":"desc","enum":["asc","desc"],"type":"string"},"description":"asc or desc."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Episode clusters across shows as the Clusters page lists them: reach by category and form, node, clip and post counts, type (`episode`, `merged`, `manual`), emptiness, freshness, sponsor brands, linked campaigns and public URL, plus `meta.totals` over reach-contributing clusters. Rows come from stored summaries (`summary_stale` marks rows that could not be recomputed).\n\n`time_range` (default `all`) buckets by the cluster's episode publish date. `series`, `guests` and `format` match the episode's tags; `custom_tags` matches node tags (applied to at most 300 rows). `state` is `all`, `active`, `empty`, `merged` or `manual`. `brand` matches sponsored-node or linked-campaign brands.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ClusterRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"totals":{"$ref":"#/components/schemas/ClusterTotals"},"window":{"$ref":"#/components/schemas/WindowInfo"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_cluster_freshness":{"additionalProperties":{"$ref":"#/components/schemas/ShowRefreshFreshness"},"description":"show id → newest cluster refresh / save.","title":"Show Cluster Freshness","type":"object"},"tag_options":{"additionalProperties":{"items":{"$ref":"#/components/schemas/TagOption"},"type":"array"},"title":"Tag Options","type":"object"},"brand_options":{"items":{"type":"string"},"title":"Brand Options","type":"array"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/clusters","data":[{"object":"cluster","total_reach":2988,"youtube_reach":732,"youtube_long_form_reach":0,"youtube_shorts_reach":732,"audio_reach":0,"social_reach":2256,"long_form_reach":0,"short_form_reach":2988,"long_form_count":0,"short_form_count":3,"clips":3,"posts":0,"total_engagement":83,"engagement_rate":2.7777777777777777,"id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Our bold predictions for the second half","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"title":"The best and worst contracts","name":"Five takeaways from the opener","internal_title":null,"cluster_type":"episode","is_merged":false,"is_manual":false,"is_empty":false,"contributing":true,"episode_ids":["0y0HEJ0OVF7EYdXAvD5ghY"],"episodes":[],"episode_count":1,"published_at":"2026-10-10","episode_date":"2026-10-10","tags":{"series":[],"guests":[],"format":[]},"custom_tags":null,"sponsor_brands":[],"brands":[],"node_count":4,"metrics_source":"nodes","summary_fresh":false,"summary_stale":false,"freshness":{"kind":"saved","at":"2026-10-12T11:17:18.153Z","source":"nodes"},"last_refreshed_at":null,"last_refresh_attempt_at":null,"last_refresh_source":null,"refresh_error_count":0,"created_at":null,"updated_at":"2026-10-12T18:40:06.002Z","auto_generated":false,"brand_collab":null,"has_emv_rates":false,"customization":null,"linked_campaign_ids":[],"linked_campaigns":[],"public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY","app_url":"https://network.listener.com/app/cluster?id=cluster-0y0HEJ0OVF7EYdXAvD5ghY&uid=paAtKPJGo56md5VyoEQ9Las7qahL"},{"object":"cluster","total_reach":409,"youtube_reach":409,"youtube_long_form_reach":65,"youtube_shorts_reach":344,"audio_reach":0,"social_reach":0,"long_form_reach":65,"short_form_reach":344,"long_form_count":1,"short_form_count":1,"clips":2,"posts":0,"total_engagement":12,"engagement_rate":2.93398533007335,"id":"cluster-7ys2rRKJbGMF7uozA47MEs","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Our bold predictions for the second half","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"title":"Is the dynasty over?","name":"Is the dynasty over?","internal_title":null,"cluster_type":"episode","is_merged":false,"is_manual":false,"is_empty":false,"contributing":true,"episode_ids":["7ys2rRKJbGMF7uozA47MEs"],"episodes":[],"episode_count":1,"published_at":"2026-10-09","episode_date":"2026-10-09","tags":{"series":[],"guests":[],"format":[]},"custom_tags":null,"sponsor_brands":[],"brands":[],"node_count":3,"metrics_source":"nodes","summary_fresh":false,"summary_stale":false,"freshness":{"kind":"unknown","at":"2026-10-09T14:52:31.648Z","source":"createdAt"},"last_refreshed_at":null,"last_refresh_attempt_at":null,"last_refresh_source":null,"refresh_error_count":0,"created_at":"2026-10-09T14:52:31.648Z","updated_at":"2026-10-12T09:02:25.056Z","auto_generated":false,"brand_collab":null,"has_emv_rates":false,"customization":null,"linked_campaign_ids":[],"linked_campaigns":[],"public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-7ys2rRKJbGMF7uozA47MEs","app_url":"https://network.listener.com/app/cluster?id=cluster-7ys2rRKJbGMF7uozA47MEs&uid=paAtKPJGo56md5VyoEQ9Las7qahL"}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"totals":{"has_clusters":true,"cluster_count":159,"source_cluster_count":144,"merged_cluster_count":15,"manual_cluster_count":11,"empty_cluster_count":22,"unlinked_cluster_count":0,"episode_count":134,"total_reach":9527003,"youtube_reach":2883483,"audio_reach":233988,"social_reach":6409532,"clips":669,"posts":161,"content_pieces":830,"avg_reach_per_episode":71097,"avg_reach_per_cluster":66160,"summary_fresh_count":0,"summary_recomputed_count":159,"summary_stale_count":0,"summary_missing_count":0},"window":{"time_range":"all","kind":"all","start":"1999-05-30","end":"2026-10-14","days":10000,"previous_start":null,"previous_end":null},"filters":{"series":null,"guests":null,"format":null,"custom_tags":null,"brand":null,"state":"all","search":null,"sort_by":"published_at","sort_order":"desc"},"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"show_cluster_freshness":{"paAtKPJGo56md5VyoEQ9Las7qahL":{"kind":"refreshed","at":"2026-10-08T05:55:29.001Z","last_refreshed_at":"2026-10-08T05:55:29.001Z","failed_node_count":0,"clusters_with_errors":0},"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H":{"kind":"saved","at":"2026-03-17T17:16:36.453Z","last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"HTSVG2lSc1RmPELJNtCnvOEb4Z2u":{"kind":"refreshed","at":"2026-08-27T10:16:43.193Z","last_refreshed_at":"2026-08-27T10:16:43.193Z","failed_node_count":0,"clusters_with_errors":0},"Xl2xMNVBZpyUA7MVJpqcKkFhEM2X":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"i3KlnFag2DgIpykraVxjrIZwJYcL":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"p3KfMe4Kfe1mY1eWjLLGFzS2wtUu":{"kind":"saved","at":"2026-04-16T13:44:46.506Z","last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"sLLP2LKo9LJHqRCtBjjWDsbyDImn":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"PXjDgD84U0pDobe25GOpKoNGTT1i":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"jgDOYIsPG3c9Jk7mysodavhQxXhV":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"Of9Els0RskCtlyZFPG8ujblH3NKI":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"2RSfMoyvMja3bzIq9vdY0UeZ0Jp8":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0},"h2DMGe9hfktytWWa0ZxVj1jMQbUb":{"kind":"unknown","at":null,"last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0}},"tag_options":{"series":[],"guests":[],"format":[]},"brand_options":["Acme Coffee","Umbrella Energy"],"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.95,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:16.117623+00:00","cache_age_seconds":10.6,"note":null,"total":159}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/clusters\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/clusters\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/clusters\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/clusters/report":{"get":{"operationId":"get_cluster_report","summary":"Cluster report","tags":["Clusters"],"parameters":[{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"categories","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only shows whose categories contain one of these (case-insensitive substring). Repeat the parameter or comma-separate values."},{"name":"time_range","in":"query","required":false,"schema":{"default":"30d","type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"include_merged","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Cluster analytics per show and for the network over a window, as the Episodes-page KPI bar computes them: reach by category (YouTube long-form and Shorts, audio, social) and form, cluster count, per-cluster averages, growth against the previous window, reach distribution, content mix and cluster counts by type.\n\nThis is cluster reach (the clips and posts attached to episodes), a different number from the account-level `GET /v1/analytics/reach`. Clusters are bucketed by their episode's publish date; merged clusters are excluded unless `include_merged=true` and never double-counted with their sources. Growth is null when the previous window had no clusters.\n\n**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`.\n\n**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`).\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetClusterReportResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_report"}}}]},"example":{"object":"cluster_report","window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"include_merged":false,"network":{"total_reach":87263,"youtube_reach":68228,"youtube_long_form_reach":64066,"youtube_shorts_reach":4162,"audio_reach":4477,"social_reach":14558,"long_form_reach":68543,"short_form_reach":18720,"long_form_count":11,"short_form_count":16,"clips":27,"posts":0,"total_engagement":1432,"engagement_rate":1.6410162382682236,"cluster_count":12,"content_pieces":27,"averages":{"avg_reach_per_cluster":7271.916666666667,"avg_youtube_reach_per_cluster":5685.666666666667,"avg_youtube_long_form_reach_per_cluster":5338.833333333333,"avg_youtube_shorts_reach_per_cluster":346.8333333333333,"avg_audio_reach_per_cluster":373.0833333333333,"avg_social_reach_per_cluster":1213.1666666666667,"avg_long_form_reach_per_cluster":5711.916666666667,"avg_short_form_reach_per_cluster":1560,"avg_long_form_count_per_cluster":0.9166666666666666,"avg_short_form_count_per_cluster":1.3333333333333333,"avg_clips_per_cluster":2.25,"avg_posts_per_cluster":0,"avg_engagement_per_cluster":119.33333333333333},"growth":{"count_growth":-33.33333333333333,"reach_growth":-96.36663346812607,"youtube_growth":-65.88787616681083,"youtube_long_form_growth":-65.49748229528502,"youtube_shorts_growth":-70.94792684629346,"audio_growth":-72.67289263260696,"social_growth":-99.33382693045131,"long_form_growth":-66.07924065166182,"short_form_growth":-99.14895319424416,"avg_reach_growth":-94.54995020218911,"avg_youtube_growth":-48.83181425021624,"avg_audio_growth":-59.009338948910454,"avg_social_growth":-99.00074039567697,"avg_long_form_growth":-49.11886097749272,"avg_short_form_growth":-98.72342979136623},"previous":{"total_reach":2401712,"youtube_reach":200011,"youtube_long_form_reach":185685,"youtube_shorts_reach":14326,"audio_reach":16383,"social_reach":2185318,"long_form_reach":202068,"short_form_reach":2199644,"long_form_count":20,"short_form_count":42,"clips":52,"posts":10,"total_engagement":16651,"engagement_rate":0.6932971147248297,"cluster_count":18},"reach_distribution":[{"name":"Mailbag: your questions answered","value":68228,"color":"#FF0000"},{"name":"What the numbers really say","value":4477,"color":"#8B5CF6"}],"content_mix":[{"name":"The rookie who changed everything","value":68543,"color":"#2563EB"},{"name":"Inside the locker room with a two-time champion","value":18720,"color":"#F59E0B"}],"has_reach_distribution_data":true,"has_content_mix_data":true,"counts":{"cluster_doc_count":159,"source_cluster_count":144,"merged_cluster_count":15,"manual_cluster_count":11,"empty_cluster_count":22,"unlinked_cluster_count":0,"undated_cluster_count":0,"episode_count":134}},"shows":[{"total_reach":86032,"youtube_reach":68228,"youtube_long_form_reach":64066,"youtube_shorts_reach":4162,"audio_reach":3246,"social_reach":14558,"long_form_reach":67312,"short_form_reach":18720,"long_form_count":10,"short_form_count":16,"clips":26,"posts":0,"total_engagement":1432,"engagement_rate":1.6644969313743725,"cluster_count":11,"content_pieces":26,"averages":{"avg_reach_per_cluster":7821.090909090909,"avg_youtube_reach_per_cluster":6202.545454545455,"avg_youtube_long_form_reach_per_cluster":5824.181818181818,"avg_youtube_shorts_reach_per_cluster":378.3636363636364,"avg_audio_reach_per_cluster":295.09090909090907,"avg_social_reach_per_cluster":1323.4545454545455,"avg_long_form_reach_per_cluster":6119.272727272727,"avg_short_form_reach_per_cluster":1701.8181818181818,"avg_long_form_count_per_cluster":0.9090909090909091,"avg_short_form_count_per_cluster":1.4545454545454546,"avg_clips_per_cluster":2.3636363636363638,"avg_posts_per_cluster":0,"avg_engagement_per_cluster":130.1818181818182},"growth":{"count_growth":-31.25,"reach_growth":-95.50045135652773,"youtube_growth":-48.27371836666616,"youtube_long_form_growth":-50.24888757736482,"youtube_shorts_growth":33.01374240971556,"audio_growth":682.1686746987953,"social_growth":-99.18199558688923,"long_form_growth":-47.89608942006998,"short_form_growth":-98.94998165833346,"avg_reach_growth":-93.45520197313122,"avg_youtube_growth":-24.76177216969623,"avg_audio_growth":1037.6998904709747,"avg_social_growth":-98.81017539911161,"avg_long_form_growth":-24.212493701919968,"avg_short_form_growth":-98.47270059393958},"previous":{"total_reach":1912014,"youtube_reach":131902,"youtube_long_form_reach":128773,"youtube_shorts_reach":3129,"audio_reach":415,"social_reach":1779697,"long_form_reach":129188,"short_form_reach":1782826,"long_form_count":17,"short_form_count":34,"clips":47,"posts":4,"total_engagement":13768,"engagement_rate":0.7200784094677131,"cluster_count":16},"reach_distribution":[{"name":"Mailbag: your questions answered","value":68228,"color":"#FF0000"},{"name":"What the numbers really say","value":3246,"color":"#8B5CF6"}],"content_mix":[{"name":"The rookie who changed everything","value":67312,"color":"#2563EB"},{"name":"Inside the locker room with a two-time champion","value":18720,"color":"#F59E0B"}],"has_reach_distribution_data":true,"has_content_mix_data":true,"counts":{"cluster_doc_count":136,"source_cluster_count":121,"merged_cluster_count":15,"manual_cluster_count":11,"empty_cluster_count":13,"unlinked_cluster_count":0,"undated_cluster_count":0,"episode_count":112},"show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Our bold predictions for the second half","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"categories":["Sports","Comedy"],"cluster_freshness":{"kind":"refreshed","at":"2026-10-08T05:55:29.001Z","last_refreshed_at":"2026-10-08T05:55:29.001Z","failed_node_count":0,"clusters_with_errors":0}},{"total_reach":0,"youtube_reach":0,"youtube_long_form_reach":0,"youtube_shorts_reach":0,"audio_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"long_form_count":0,"short_form_count":0,"clips":0,"posts":0,"total_engagement":0,"engagement_rate":0,"cluster_count":0,"content_pieces":0,"averages":{"avg_reach_per_cluster":0,"avg_youtube_reach_per_cluster":0,"avg_youtube_long_form_reach_per_cluster":0,"avg_youtube_shorts_reach_per_cluster":0,"avg_audio_reach_per_cluster":0,"avg_social_reach_per_cluster":0,"avg_long_form_reach_per_cluster":0,"avg_short_form_reach_per_cluster":0,"avg_long_form_count_per_cluster":0,"avg_short_form_count_per_cluster":0,"avg_clips_per_cluster":0,"avg_posts_per_cluster":0,"avg_engagement_per_cluster":0},"growth":{"count_growth":-100.0,"reach_growth":-100.0,"youtube_growth":-100.0,"youtube_long_form_growth":-100.0,"youtube_shorts_growth":-100.0,"audio_growth":-100.0,"social_growth":-100.0,"long_form_growth":-100.0,"short_form_growth":-100.0,"avg_reach_growth":-100.0,"avg_youtube_growth":-100.0,"avg_audio_growth":-100.0,"avg_social_growth":-100.0,"avg_long_form_growth":-100.0,"avg_short_form_growth":-100.0},"previous":{"total_reach":489698,"youtube_reach":68109,"youtube_long_form_reach":56912,"youtube_shorts_reach":11197,"audio_reach":15968,"social_reach":405621,"long_form_reach":72880,"short_form_reach":416818,"long_form_count":3,"short_form_count":8,"clips":5,"posts":6,"total_engagement":2883,"engagement_rate":0.588730196978546,"cluster_count":2},"reach_distribution":[{"name":"Mailbag: your questions answered","value":0,"color":"#FF0000"},{"name":"What the numbers really say","value":0,"color":"#8B5CF6"}],"content_mix":[{"name":"The rookie who changed everything","value":0,"color":"#2563EB"},{"name":"Inside the locker room with a two-time champion","value":0,"color":"#F59E0B"}],"has_reach_distribution_data":false,"has_content_mix_data":false,"counts":{"cluster_doc_count":16,"source_cluster_count":16,"merged_cluster_count":0,"manual_cluster_count":0,"empty_cluster_count":7,"unlinked_cluster_count":0,"undated_cluster_count":0,"episode_count":16},"show":{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"Mailbag: your questions answered","handle":"the-bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","public_url":"https://listener.com/the-bullpen"},"categories":["Fantasy Sports","Sports News"],"cluster_freshness":{"kind":"saved","at":"2026-03-17T17:16:36.453Z","last_refreshed_at":null,"failed_node_count":0,"clusters_with_errors":0}}],"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"categories":null,"coverage":{"start":"2025-01-14","embedded_boundary":null,"history_used":false,"previous_window_coverage_days":14,"current_window_coverage_days":8,"growth_basis":"total","growth_platforms":null,"warnings":["The Long Game: no clusters in the previous window, growth is null."]},"freshness":{"applePodcasts":{"last_updated":"2026-04-13T16:00:26+00:00","age_hours":4417.56,"stale":true},"facebook":{"last_updated":"2026-10-08T07:02:13.420000+00:00","age_hours":154.53,"stale":true},"instagram":{"last_updated":"2026-10-13T09:35:13.282000+00:00","age_hours":31.98,"stale":false},"megaphone":{"last_updated":"2026-10-14T09:22:51.743000+00:00","age_hours":8.19,"stale":false},"omnystudio":{"last_updated":"2026-10-13T09:33:48.789000+00:00","age_hours":32.01,"stale":false},"spotify":{"last_updated":"2026-08-06T08:49:48.390000+00:00","age_hours":1664.74,"stale":true},"threads":{"last_updated":"2026-10-13T09:36:40.899000+00:00","age_hours":31.96,"stale":false},"tiktok":{"last_updated":"2026-10-13T09:34:15.574000+00:00","age_hours":32.0,"stale":false},"twitter":{"last_updated":"2026-10-10T07:02:33.014000+00:00","age_hours":106.53,"stale":true},"youtube":{"last_updated":"2026-10-02T10:37:33.857000+00:00","age_hours":294.95,"stale":true}},"stale_platforms":["applePodcasts","facebook"],"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"summary_stale_count":0,"computed_at":"2026-10-14T17:34:16.152082+00:00","cache_age_seconds":10.6,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/clusters/report\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/clusters/report\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/clusters/report\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters":{"post":{"operationId":"create_cluster","summary":"Create a cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Create a cluster for a show: an episode cluster (one id in `episode_ids`), a merged cluster (two or more ids) or a manual cluster (`manual: {name, …}`, no episode ids). Episode ids must be episodes of the show. `content_nodes` optionally attaches clips and posts (`platform` label such as \"YouTube Shorts\", `url`, optional `type`, `title`, `thumbnail`, `views`, `likes`, `comments`, `date`). An existing cluster id is never overwritten; a merged cluster first creates any missing per-episode clusters.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"episode_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Episode ids on the show."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Name."},"internal_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"content_nodes":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null},"manual":{"anyOf":[{"$ref":"#/components/schemas/ManualClusterInput"},{"type":"null"}],"default":null},"emv_rates":{"anyOf":[{"$ref":"#/components/schemas/EmvRatesInput"},{"type":"null"}],"default":null,"description":"EMV rates: {long_form_cpm, short_form_cpm, like_rate, comment_rate}."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/manual-cluster-7507348341473","id":"manual-cluster-7507348341473","method":"transaction","written":{"id":"manual-cluster-7507348341473","userId":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"The comeback nobody saw coming","description":"","date":"","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","cover":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","selectedEpisodes":["manual-7507348341473"],"episodeIds":["manual-7507348341473"],"nodes":[{"id":"episode-manual-7507348341473","type":"episode","position":{"x":250,"y":50},"data":{"id":"episode-manual-7507348341473","title":"The comeback nobody saw coming","description":"","date":"","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","cover":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","duration":"0:00","durationMinutes":0,"isManual":true,"addedAt":"2026-10-14T17:34:16.341Z"}}],"edges":[],"createdAt":"2026-10-14T17:34:16.341Z","updatedAt":"2026-10-14T17:34:16.341Z","isManual":true},"warnings":["No `summary` was written; the All clusters list recomputes it on next load."],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=manual-7507348341473","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_manual-cluster-7507348341473"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","episode_row":{"id":"manual-7507348341473","title":"The comeback nobody saw coming","description":"","date":"","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","cover":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","duration":"0:00","durationMinutes":0,"isManual":true,"addedAt":"2026-10-14T17:34:16.341Z"},"cluster_id":"manual-cluster-7507348341473","node_count":1,"edge_count":0,"episode_ids":["manual-7507348341473"],"kind":"manual"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/clusters\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/merge":{"post":{"operationId":"merge_clusters","summary":"Merge episode clusters","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Build, or rebuild, the merged cluster for several episodes from their episode clusters. Source clusters are never modified; missing ones are created first. Rebuilding keeps the merged cluster's EMV rates, customization, internal title, brand collaboration and creation date.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"episode_ids":{"items":{"type":"string"},"maxItems":50,"minItems":2,"type":"array","description":"Episode ids on the show."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Name."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["episode_ids"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-merged-7ys2rRKJbGMF7uozA47MEs-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-merged-7ys2rRKJbGMF7uozA47MEs-0y0HEJ0OVF7EYdXAvD5ghY","method":"set-merge","written":{"id":"cluster-merged-7ys2rRKJbGMF7uozA47MEs-0y0HEJ0OVF7EYdXAvD5ghY","userId":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Playoff picture, explained","description":"","selectedEpisodes":["7ys2rRKJbGMF7uozA47MEs","0y0HEJ0OVF7EYdXAvD5ghY"],"episodeIds":["7ys2rRKJbGMF7uozA47MEs","0y0HEJ0OVF7EYdXAvD5ghY"],"nodes":[{"id":"episode-7ys2rRKJbGMF7uozA47MEs","type":"episode","position":{"x":250,"y":50},"data":{"id":"episode-7ys2rRKJbGMF7uozA47MEs","title":"Draft night grades","date":""}},{"id":"episode-0y0HEJ0OVF7EYdXAvD5ghY","type":"episode","position":{"x":600,"y":50},"data":{"id":"episode-0y0HEJ0OVF7EYdXAvD5ghY","title":"Power rankings, week 6","date":""}}],"edges":[{"source":"episode-7ys2rRKJbGMF7uozA47MEs","id":"edge-episode-7ys2rRKJbGMF7uozA47MEs-clip-8194150637810-8235","target":"clip-8194150637810-8235","type":"default"},{"source":"episode-7ys2rRKJbGMF7uozA47MEs","id":"edge-episode-7ys2rRKJbGMF7uozA47MEs-clip-3445805415745-785","target":"clip-3445805415745-785","type":"default"}],"createdAt":"2026-10-14T17:34:17.480Z","updatedAt":"2026-10-14T17:34:17.480Z","mergedTemplateId":null,"mergedTemplateMetric":null,"mergedTemplateRange":{"preset":"all","customFrom":null,"customTo":null}},"warnings":["No `summary` was written; the All clusters list recomputes it on next load."],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episodes=7ys2rRKJbGMF7uozA47MEs%2C0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-merged-7ys2rRKJbGMF7uozA47MEs-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-merged-7ys2rRKJbGMF7uozA47MEs-0y0HEJ0OVF7EYdXAvD5ghY","episode_ids":["7ys2rRKJbGMF7uozA47MEs","0y0HEJ0OVF7EYdXAvD5ghY"],"node_count":7,"edge_count":5,"existed":false,"carried_forward":[]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/clusters/merge\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"episode_ids\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/merge\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"episode_ids\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/merge\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'episode_ids': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/{cluster_id}":{"get":{"operationId":"get_cluster","summary":"Retrieve a cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"name":"include_nodes","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"name":"node_limit","in":"query","required":false,"schema":{"default":200,"maximum":1000,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One cluster in full: metadata (type, episodes, customization, brand collaboration), 14 reach and engagement metrics computed from its nodes, every content node (platform, URL, reach, category, form, engagement, publish date, custom tags, sponsor, `parent_id` / `child_ids` canvas links), the canvas edges, subcluster rollups, custom-tag rollups, linked campaigns, the EMV estimate with the rate precedence used, the first-30-days estimate, refresh freshness and errors, and share URLs.\n\nNodes are sorted by reach and capped at `node_limit` (`nodes_truncated` says when more exist); `edges` and `subclusters` always cover the whole cluster. Rebuild the canvas tree by grouping nodes on `parent_id`.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetClusterResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster"}}}]},"example":{"object":"cluster","cluster":{"id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Our bold predictions for the second half","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"title":"The best and worst contracts","name":"Five takeaways from the opener","internal_title":null,"description":null,"cluster_type":"episode","is_merged":false,"is_manual":false,"is_empty":false,"contributing":true,"episode_ids":["0y0HEJ0OVF7EYdXAvD5ghY"],"episodes":[],"published_at":"2026-10-10","episode_date":"2026-10-10","tags":{"series":[],"guests":[],"format":[]},"customization":null,"brand_collab":null,"emv_rates":null,"auto_generated":false,"created_at":null,"updated_at":"2026-10-12T18:40:06.002Z","public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY","app_url":"https://network.listener.com/app/cluster?id=cluster-0y0HEJ0OVF7EYdXAvD5ghY&uid=paAtKPJGo56md5VyoEQ9Las7qahL"},"metrics":{"total_reach":2988,"youtube_reach":732,"youtube_long_form_reach":0,"youtube_shorts_reach":732,"audio_reach":0,"social_reach":2256,"long_form_reach":0,"short_form_reach":2988,"long_form_count":0,"short_form_count":3,"clips":3,"posts":0,"total_engagement":83,"engagement_rate":2.7777777777777777},"metrics_source":"nodes","first_30_days":{"total_reach":2988,"youtube_reach":732,"youtube_long_form_reach":0,"youtube_shorts_reach":732,"audio_reach":0,"social_reach":2256,"long_form_reach":0,"short_form_reach":2988,"long_form_count":0,"short_form_count":3,"clips":3,"posts":0,"total_engagement":83,"engagement_rate":2.7777777777777777,"availability":{"available":true,"reason":null,"dated_count":3,"total_count":3,"undated_with_metrics_count":0},"as_of":"2026-10-14T17:34:18.674Z"},"emv":{"total":81.26,"long_form_value":0.0,"short_form_value":59.76,"like_value":20.25,"comment_value":1.25,"engagement_value":21.5,"nodes":3,"includes_engagement":true,"method":"nodes","rates":{"long_form_cpm":25,"short_form_cpm":20,"like_rate":0.25,"comment_rate":1.25,"show_on_share_page":true},"inherited_rates":{"long_form_cpm":25,"short_form_cpm":20,"like_rate":0.25,"comment_rate":1.25,"show_on_share_page":true},"rates_source":"network","rates_campaign_id":null},"node_count":4,"nodes":[{"id":"clip-0718188106790-9358","type":"clip","platform":"Instagram","platform_key":"instagram","platform_raw":"Instagram","url":"https://www.instagram.com/reel/VvUVi4qn6K0/","title":"Draft night grades","thumbnail":"https://images.example.com/listener/5549925bd54f80de.jpg","published_at":"2026-10-10","reach":1784,"reach_category":"social","reach_contributions":{"youtube":0,"audio":0,"social":1784},"video_form":"short","is_long_form":false,"youtube_bucket":null,"engagement":36,"engagement_breakdown":{"likes":36,"comments":0,"shares":0,"reposts":0,"retweets":0,"replies":0,"quotes":0,"reactions":0,"appreciations":0,"empathy":0,"praises":0},"custom_tags":[],"is_sponsored":false,"sponsor_brand":null,"is_pending":false,"no_data_returned":false,"is_shorts":false,"is_selection_episode":false,"episode_id":null,"source_show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","ai_relevance_score":null,"last_updated":null,"podcast_downloads":null,"podcast_downloads_source":null,"podcast_downloads_api":null,"source_content_id":null,"parent_id":"episode-0y0HEJ0OVF7EYdXAvD5ghY","parent_ids":["episode-0y0HEJ0OVF7EYdXAvD5ghY"],"parent_url":"https://open.spotify.com/episode/0y0HEJ0OVF7EYdXAvD5ghY","child_ids":[],"connected_to":["episode-0y0HEJ0OVF7EYdXAvD5ghY"],"subcluster_id":null,"subcluster_name":null,"subcluster_ids":[],"is_subcluster_anchor":false},{"id":"clip-4547877422640-8832","type":"clip","platform":"YouTube","platform_key":"youtube","platform_raw":"YouTube Shorts","url":"https://www.youtube.com/shorts/UomV7A7ON2m","title":"Five takeaways from the opener","thumbnail":"https://images.example.com/listener/494d89fc43becd8a.jpg","published_at":"2026-10-10","reach":732,"reach_category":"youtube","reach_contributions":{"youtube":732,"audio":0,"social":0},"video_form":"short","is_long_form":false,"youtube_bucket":"youtube_shorts_reach","engagement":18,"engagement_breakdown":{"likes":17,"comments":1,"shares":0,"reposts":0,"retweets":0,"replies":0,"quotes":0,"reactions":0,"appreciations":0,"empathy":0,"praises":0},"custom_tags":[],"is_sponsored":false,"sponsor_brand":null,"is_pending":false,"no_data_returned":false,"is_shorts":true,"is_selection_episode":false,"episode_id":null,"source_show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","ai_relevance_score":null,"last_updated":null,"podcast_downloads":null,"podcast_downloads_source":null,"podcast_downloads_api":null,"source_content_id":null,"parent_id":"episode-0y0HEJ0OVF7EYdXAvD5ghY","parent_ids":["episode-0y0HEJ0OVF7EYdXAvD5ghY"],"parent_url":"https://open.spotify.com/episode/0y0HEJ0OVF7EYdXAvD5ghY","child_ids":[],"connected_to":["episode-0y0HEJ0OVF7EYdXAvD5ghY"],"subcluster_id":null,"subcluster_name":null,"subcluster_ids":[],"is_subcluster_anchor":false}],"nodes_truncated":false,"nodes_returned":4,"tag_rollups":{"rows":[{"tag":"Untagged","key":"__untagged__","is_untagged":true,"pieces":4,"reach":2988,"engagement":83,"engagement_rate":2.7777777777777777,"share_of_reach":1.0,"platforms":[{"platform":"Instagram","pieces":1,"reach":1784},{"platform":"YouTube Shorts","pieces":1,"reach":732}]}],"total_reach":2988,"total_engagement":83,"content_node_count":4,"tagged_node_count":0,"untagged_node_count":4,"multi_tagged_node_count":0,"has_tags":false},"subclusters":{"rows":[],"subcluster_count":0,"average_reach":0,"total_reach":2988,"total_engagement":83,"content_node_count":4,"grouped_node_count":0,"unassigned_node_count":4,"multi_subcluster_node_count":0,"has_subclusters":false},"edges":[{"source":"episode-0y0HEJ0OVF7EYdXAvD5ghY","target":"clip-0718188106790-9358"},{"source":"episode-0y0HEJ0OVF7EYdXAvD5ghY","target":"clip-4547877422640-8832"}],"sponsor_brands":[],"brands":[],"linked_campaigns":[],"freshness":{"kind":"saved","at":"2026-10-12T11:17:18.153Z","source":"nodes"},"last_refreshed_at":null,"last_refresh_attempt_at":null,"last_refresh_source":null,"refresh_errors":[],"refresh_error_count":0,"platform_freshness":{"youtube":{"last_updated":"2026-10-14T07:52:53.974000+00:00","age_hours":9.69,"stale":false},"spotify":{"last_updated":"2026-10-14T07:20:29.026000+00:00","age_hours":10.23,"stale":false},"applePodcasts":{"last_updated":"2026-04-13T17:36:30+00:00","age_hours":4415.96,"stale":true},"tiktok":{"last_updated":"2026-10-14T07:54:34.140000+00:00","age_hours":9.66,"stale":false},"instagram":{"last_updated":"2026-10-14T07:54:18.265000+00:00","age_hours":9.67,"stale":false},"twitter":{"last_updated":"2026-10-14T07:55:11.134000+00:00","age_hours":9.65,"stale":false}},"stale_platforms":["applePodcasts"],"computed_at":"2026-10-14T17:34:18.669983+00:00","cache_age_seconds":13.1,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"patch":{"operationId":"update_cluster","summary":"Update a cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Update cluster metadata: name, internal title, description, image, cover, date, public-page `customization`, `emv_rates` and `brand_collab`. Only the fields you send change. `emv_rates` merges over the current rates; `customization` merges over the stored page overrides, and `customization.co_brand` (`{name, logo_url, href}`, https URLs) adds a partner co-brand to the public cluster page (`\"co_brand\": null` removes it); `clear_customization`, `clear_internal_title` and `clear_brand_collab` remove those fields. Description, image, cover and date on non-manual clusters last only until the next canvas save in the app.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Name."},"internal_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"clear_internal_title":{"default":false,"type":"boolean"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Free-text description."},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"cover":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"customization":{"anyOf":[{"$ref":"#/components/schemas/ClusterCustomizationInput"},{"type":"null"}],"default":null},"clear_customization":{"default":false,"type":"boolean"},"emv_rates":{"anyOf":[{"$ref":"#/components/schemas/EmvRatesInput"},{"type":"null"}],"default":null,"description":"EMV rates: {long_form_cpm, short_form_cpm, like_rate, comment_rate}."},"brand_collab":{"anyOf":[{"$ref":"#/components/schemas/BrandCollabInput"},{"type":"null"}],"default":null},"clear_brand_collab":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"update","written":{"internalTitle":"API probe","updatedAt":"2026-10-14T17:34:19.009Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]},"delete":{"operationId":"delete_cluster","summary":"Delete a cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"name":"allow_merged","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"name":"confirm","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Permanently delete a cluster (no undo) and report, without fixing, the campaigns and shared reports that still reference it. Send `?dry_run=true` first to see them. A manual cluster's synthetic episode is removed too. Clusters spanning several episodes are refused unless `allow_merged=true`.\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `?confirm=true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `clusters:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"transaction","written":{"deleted":true,"cluster":{"id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","name":"Five takeaways from the opener","episode_ids":["0y0HEJ0OVF7EYdXAvD5ghY"]},"show_doc_updates":{},"dangling":{"campaign_ids":[],"shared_report_ids":["U408eAHMUK0pl7OlcvFU","yDOF1QDhp4fJsSahuI0L"]}},"warnings":["Shared report(s) embed this cluster (not fixed): U408eAHMUK0pl7OlcvFU, yDOF1QDhp4fJsSahuI0L."],"urls":{"app":"https://network.listener.com/app/episodes?uid=paAtKPJGo56md5VyoEQ9Las7qahL","public":null},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","episode_ids":["0y0HEJ0OVF7EYdXAvD5ghY"],"dangling":{"campaign_ids":[],"shared_report_ids":["U408eAHMUK0pl7OlcvFU","yDOF1QDhp4fJsSahuI0L"]},"confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/{cluster_id}/timeline":{"get":{"operationId":"get_cluster_timeline","summary":"Cluster timeline","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"name":"granularity","in":"query","required":false,"schema":{"default":"daily","enum":["daily","weekly","monthly"],"type":"string"}},{"name":"chart_type","in":"query","required":false,"schema":{"default":"cumulative","enum":["daily","cumulative"],"type":"string"},"description":"daily values or a cumulative running total."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The cluster page's \"views / engagement over time\" curve (`granularity` daily, weekly or monthly; `chart_type` cumulative or per period). It spreads the cluster's lifetime totals from its earliest episode date to today on a fixed decay, so `synthetic` is always true; for measured dates use the nodes' `published_at` from `GET /v1/shows/{show_id}/clusters/{cluster_id}`.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetClusterTimelineResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_timeline"}}}]},"example":{"object":"cluster_timeline","show":{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Our bold predictions for the second half","handle":"hard-court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court"},"cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","title":"The best and worst contracts","granularity":"daily","chart_type":"cumulative","synthetic":true,"start_date":"2026-10-10","start_date_from_episode":true,"total_days":5,"data_points":5,"total_views":2988,"total_engagement":83,"points":[{"date":"2026-10-10","views":1363,"engagement":12},{"date":"2026-10-11","views":2138,"engagement":29}],"computed_at":"2026-10-14T17:34:21.296110+00:00","cache_age_seconds":15.8,"note":"Shape-only series: the cluster's lifetime totals spread from the earliest episode date to today on the app's fixed curve. Use node_publish_timeline for measured buckets."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/timeline\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/timeline\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/timeline\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/{episode_id}/posts":{"post":{"operationId":"add_posts_to_cluster","summary":"Add posts to an episode's cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"path","required":true,"schema":{"type":"string"},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Add clips or posts to an episode's cluster by URL (YouTube, Shorts, TikTok, Instagram, Facebook, X, Threads, LinkedIn and the show's own Substack posts), including posts from accounts that are not connected. Each link is fetched (title, thumbnail, views, likes, comments) and added as a node; the cluster is created when the episode has none. Links already in the cluster are skipped. Up to 25 URLs per request. A dry run checks every link (supported platform, duplicates, whether a cluster will be created) without fetching.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"items":{"type":"string"},"maxItems":25,"minItems":1,"type":"array","description":"Post or clip URLs (up to 25)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["urls"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"http","written":{"episodeId":"0y0HEJ0OVF7EYdXAvD5ghY","urls":["https://www.youtube.com/shorts/wig-TZ-bpZD"]},"warnings":[],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","episode_id":"0y0HEJ0OVF7EYdXAvD5ghY","episode_title":"The best and worst contracts","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","would_add":[{"url":"https://www.youtube.com/shorts/wig-TZ-bpZD","platform":"YouTube Shorts"}],"already_in_cluster":[],"rejected":[]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/posts\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"urls\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/posts\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"urls\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/posts\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'urls': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/{cluster_id}/nodes/remove":{"post":{"operationId":"remove_cluster_nodes","summary":"Remove cluster nodes","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Remove nodes, and every edge touching them, from a cluster. The last episode node cannot be removed; to remove the whole cluster use `DELETE /v1/shows/{show_id}/clusters/{cluster_id}`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_ids":{"items":{"type":"string"},"maxItems":500,"minItems":1,"type":"array","description":"Cluster node ids."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["node_ids"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"transaction","written":{"nodes":"<3 nodes>","edges":"<2 edges>","updatedAt":"2026-10-14T17:34:22.771Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","removed":["clip-0718188106790-9358"],"node_count":3,"edges_removed":1},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/remove\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"node_ids\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/remove\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"node_ids\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/remove\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'node_ids': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/{cluster_id}/nodes/tags":{"post":{"operationId":"set_cluster_node_tags","summary":"Set cluster node tags","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set, add or remove custom tags on specific cluster nodes (`mode` = `replace`, `add`, `remove`). Tags are trimmed and de-duplicated case-insensitively; only episode, clip and post nodes take tags (others come back in `data.skipped`); unknown node ids are an error. Episode tags are a separate system (`POST /v1/shows/{show_id}/episodes/tags`).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_ids":{"items":{"type":"string"},"maxItems":500,"minItems":1,"type":"array","description":"Cluster node ids."},"tags":{"items":{"type":"string"},"type":"array","description":"Tags to apply."},"mode":{"default":"replace","enum":["replace","add","remove"],"type":"string","description":"How the change applies (see the operation description)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["node_ids","tags"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"transaction","written":{"nodes":"<4 nodes>","updatedAt":"2026-10-14T17:34:23.104Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","tags_by_node":{"clip-0718188106790-9358":["API probe"]},"skipped":[]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/tags\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"node_ids\": [], \"tags\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/tags\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"node_ids\": [], \"tags\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/nodes/tags\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'node_ids': [], 'tags': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/clusters/{cluster_id}/refresh":{"post":{"operationId":"refresh_cluster","summary":"Refresh a cluster's metrics","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string"},"description":"Cluster id (see GET /v1/clusters)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Re-fetch every clip and post of one cluster from its platforms and return per-platform node counts, the provider-call estimate and the result. Needs `\"confirm\": true` (one metered provider call per node). Merged clusters are refused; refresh their source clusters. A node whose fresh value reads 0 keeps its previous value.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `\"confirm\": true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `refresh:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster_refresh","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"http","written":{"uid":"paAtKPJGo56md5VyoEQ9Las7qahL","clusterId":"cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"warnings":["A node whose fresh value reads 0 keeps its previous value (treated as a failed fetch)."],"urls":{"app":"https://network.listener.com/app/cluster?uid=paAtKPJGo56md5VyoEQ9Las7qahL&episode=0y0HEJ0OVF7EYdXAvD5ghY","public":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"error":null,"data":{"show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","estimated_provider_calls":3,"per_platform":{"YouTube Shorts":1,"Instagram":1,"TikTok":1},"last_refreshed_at":null,"last_refresh_attempt_at":null,"status":"would-refresh"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["refresh:write"]}],"x-required-scope":"refresh:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/refresh\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/refresh\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/clusters/CLUSTER_ID/refresh\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/cluster-sources":{"get":{"operationId":"get_cluster_sources","summary":"Accounts the cluster builder searches","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The accounts the cluster builder searches for a show's clips and posts: connected accounts, accounts learned from the show's past clusters (with their share of past nodes) and accounts a person added, each with platform, handle, role (`own`, `partner`, `guest`) and on/off, plus the date window around each episode. The first request for a show learns the list from its past clusters (no cluster is modified). `configured=false` means the builder is not reachable from this server.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ClusterSourcesResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_sources"}}}]},"example":{"object":"cluster_sources","show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","configured":false,"handles":[],"enabled_count":0,"by_platform":{},"window":null,"learned_at":null,"updated_at":null,"app_url":null,"computed_at":"2026-10-14T17:34:23.437868+00:00","cache_age_seconds":17.9,"note":"The cluster builder is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"patch":{"operationId":"update_cluster_sources","summary":"Update the cluster builder's accounts","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Change which accounts the cluster builder searches for a show: `add` accounts (profile URL, `platform:handle` or `{handle, platform, role}`), `remove` accounts a person added, or `enable` / `disable` any account (`platform:handle`, `@handle` or a profile URL). Connected and learned accounts can only be turned off. Added accounts default to role `partner`; use `own` for the show's brand accounts and `guest` for a guest. Takes effect on the next build or content search.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"anyOf":[{"items":{"$ref":"#/components/schemas/SourceHandleInput"},"type":"array"},{"type":"null"}],"default":null},"remove":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"enable":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"disable":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster_sources","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"clusterSources/paAtKPJGo56md5VyoEQ9Las7qahL","id":"paAtKPJGo56md5VyoEQ9Las7qahL","method":"set-merge","written":{"handles":[{"platform":"tiktok","handle":"ttcnnerju78","role":"partner","enabled":true,"added_by":"person"}]},"warnings":[],"urls":{"app":null,"public":null},"error":null,"data":{"added":["tiktok:listenerprobe"],"removed":[],"enabled":[],"disabled":[],"handle_count":9},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/shows/SHOW_ID/cluster-sources\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/cluster-candidates":{"get":{"operationId":"find_episodes_to_cluster","summary":"Episodes to cluster","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Search text."},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Earliest publish date, YYYY-MM-DD."},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Latest publish date, YYYY-MM-DD."},{"name":"limit","in":"query","required":false,"schema":{"default":30,"maximum":200,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The show's episodes as the cluster builder sees them, newest first, including the newest episodes from the live feed that the episodes list may not have yet: id, title, date, whether it has a cluster, its build status (`ready` = suggestions waiting) and source (`stored` or `live`). `query` keeps titles containing every word; `from_date` / `to_date` bound the publish date. Not paginated.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/BuildEpisode"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_candidate"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"configured":{"title":"Configured","type":"boolean"},"total":{"default":0,"title":"Total","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/shows/i3KlnFag2DgIpykraVxjrIZwJYcL/cluster-candidates","data":[],"has_more":false,"next_cursor":null,"meta":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","configured":false,"total":0,"computed_at":"2026-10-14T17:34:23.603774+00:00","cache_age_seconds":18.1,"note":"The cluster builder is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app."}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/cluster-candidates\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/cluster-candidates\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/cluster-candidates\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/{episode_id}/content-candidates":{"get":{"operationId":"find_episode_content","summary":"Find an episode's clips and posts","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Search text."},{"name":"handles","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Repeat the parameter or comma-separate values."},{"name":"platforms","in":"query","required":false,"schema":{"anyOf":[{"items":{"enum":["tiktok","instagram","facebook","x","youtube","threads","linkedin"],"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Only these platforms (e.g. youtube, spotify, instagram; aliases accepted). Repeat the parameter or comma-separate values."},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Earliest publish date, YYYY-MM-DD."},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Latest publish date, YYYY-MM-DD."},{"name":"limit","in":"query","required":false,"schema":{"default":30,"maximum":100,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"name":"judge","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Find the clips and posts that belong to one episode, including external posts not in the Listener library: searches the show's connected accounts, every enabled account in its cluster sources and any extra `handles`, then an AI judge scores each candidate (confidence, `sure` / `likely`, reason) and flags the ones already in the cluster.\n\n`handles` adds accounts for this search only (`x:northwindaudio`, `tiktok:@name`, a profile URL, or `@name` with `platforms`). `query` (a guest, a topic) is a ranking hint, never a filter; `judge=false` skips the scoring (faster). `from_date` / `to_date` override the window around the episode date. Writes nothing, but external accounts can spend scraper credits on their first fetch of a month. Add the posts you pick with `POST /v1/shows/{show_id}/episodes/{episode_id}/posts`.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FindEpisodeContentResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"content_candidates"}}}]},"example":{"object":"content_candidates","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_name":"Hard Court","configured":false,"episode":null,"candidates":[],"items":[],"total":0,"library_count":0,"external_count":0,"sure_count":0,"in_cluster_count":0,"searched_handles":[],"searched":[],"window":null,"computed_at":"2026-10-14T17:34:23.605720+00:00","cache_age_seconds":18.1,"note":"The cluster builder is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/content-candidates\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/content-candidates\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/EPISODE_ID/content-candidates\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/cluster-builds":{"post":{"operationId":"build_clusters","summary":"Start an AI cluster build","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Build episode clusters with AI for a period or chosen episodes: for every episode in scope the builder gathers clips and posts from the show's connected and other accounts, judges which belong to the episode, and records suggestions (`mode=suggest`, default) or writes the sure ones straight into clusters (`mode=auto`).\n\nSend `\"dry_run\": true` first: `would_write.data.estimate` gives episodes in scope, already clustered, to build, minutes and scraper credits. The real request starts a background job (`data.job.job_id`); follow it with `GET /v1/cluster-builds/{job_id}`, then review with `GET /v1/shows/{show_id}/cluster-suggestions`. `scope`: `week`, `last30`, `range` (`from_date` + `to_date`), `backcatalog` (up to 500 episodes per job) or `episodes` (`episode_ids`). Clustered episodes are skipped unless `force=true`. One job runs per show; starting another returns the running one (`data.already_running`).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"show_id":{"type":"string","description":"A show id in this workspace (see GET /v1/shows)."},"scope":{"default":"week","enum":["week","last30","range","backcatalog","episodes"],"type":"string"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Earliest publish date, YYYY-MM-DD."},"to_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Latest publish date, YYYY-MM-DD."},"episode_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Episode ids on the show."},"mode":{"default":"suggest","enum":["suggest","auto"],"type":"string","description":"How the change applies (see the operation description)."},"force":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["show_id"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster_build","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"clusterBuildJobs/paAtKPJGo56md5VyoEQ9Las7qahL","id":"paAtKPJGo56md5VyoEQ9Las7qahL","method":"http","written":{"scope":"week","mode":"suggest"},"warnings":[],"urls":{"app":null,"public":null},"error":null,"data":{"estimate":{"episodes_in_scope":5,"already_clustered":2,"to_build":3,"minutes":6,"scraper_credits":42}},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/cluster-builds\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"show_id\": \"SHOW_ID\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/cluster-builds\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"show_id\": \"SHOW_ID\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/cluster-builds\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'show_id': 'SHOW_ID', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/cluster-builds/latest":{"get":{"operationId":"get_latest_cluster_build","summary":"Retrieve a show's latest cluster build","tags":["Clusters"],"parameters":[{"name":"show_id","in":"query","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"wait_seconds","in":"query","required":false,"schema":{"default":0,"maximum":50,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The show's most recent cluster build: status, done / total, current `phase` and episode, counts (built, ready to review, nothing found, failed, skipped), per-episode outcomes, a one-line `summary` and the app link where suggestions are reviewed. Never cached; `wait_seconds` (up to 50) returns as soon as the job progresses.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ClusterBuildResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_build"}}}]},"example":{"object":"cluster_build","show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","configured":false,"job":null,"finished":false,"summary":"","outcomes":[],"review_url":null,"computed_at":"2026-10-14T17:34:23.789055+00:00","cache_age_seconds":18.3,"note":"The cluster builder is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/cluster-builds/latest?show_id=SHOW_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/cluster-builds/latest?show_id=SHOW_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/cluster-builds/latest?show_id=SHOW_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/cluster-builds/{job_id}":{"get":{"operationId":"get_cluster_build","summary":"Retrieve a cluster build","tags":["Clusters"],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Cluster build job id returned by POST /v1/cluster-builds."},{"name":"show_id","in":"query","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"wait_seconds","in":"query","required":false,"schema":{"default":0,"maximum":50,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One cluster build job (from `POST /v1/cluster-builds`): status, done / total, current `phase` and episode, counts (built, ready to review, nothing found, failed, skipped), per-episode outcomes, a one-line `summary` and the review link. Never cached. To follow a running job pass `wait_seconds` (up to 50): the request returns as soon as the job progresses or finishes.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ClusterBuildResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_build"}}}]},"example":{"object":"cluster_build","show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","configured":false,"job":null,"finished":false,"summary":"","outcomes":[],"review_url":null,"computed_at":"2026-10-14T17:34:23.790855+00:00","cache_age_seconds":18.3,"note":"The cluster builder is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/cluster-builds/JOB_ID?show_id=SHOW_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/cluster-builds/JOB_ID?show_id=SHOW_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/cluster-builds/JOB_ID?show_id=SHOW_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/cluster-suggestions":{"get":{"operationId":"list_cluster_suggestions","summary":"List cluster suggestions","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"status","in":"query","required":false,"schema":{"default":"ready","enum":["ready","building","built","accepted","nothing","failed","dismissed","all"],"type":"string"},"description":"Status filter or value."},{"name":"limit","in":"query","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"name":"items_per_episode","in":"query","required":false,"schema":{"default":25,"maximum":100,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Episodes with AI cluster suggestions, newest first (`status=ready` by default), each with its suggested clips and posts: key, platform, title, URL, handle, source (`library` or `external`), confidence, label (`sure` / `likely`), reason and metrics. Other statuses: `built`, `accepted`, `nothing`, `failed`, `building`, `dismissed`, `all`. `items_per_episode=0` returns counts only. Not paginated; `has_more` says when more episodes wait.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SuggestionEpisode"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"cluster_suggestion"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"status":{"title":"Status","type":"string"},"total":{"title":"Total","type":"integer"},"has_more":{"default":false,"title":"Has More","type":"boolean"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Review Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/shows/i3KlnFag2DgIpykraVxjrIZwJYcL/cluster-suggestions","data":[],"has_more":false,"next_cursor":null,"meta":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","status":"ready","total":0,"review_url":"https://network.listener.com/app/episodes?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","computed_at":"2026-10-14T17:34:23.793221+00:00","cache_age_seconds":18.3,"note":"Nothing is waiting for review. Run `POST /v1/cluster-builds` to look for posts, or `GET /v1/shows/{show_id}/episodes/{episode_id}/content-candidates` for one episode."}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/cluster-suggestions/{episode_id}/review":{"post":{"operationId":"review_cluster_suggestions","summary":"Review cluster suggestions","tags":["Clusters"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"path","required":true,"schema":{"type":"string"},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Accept or dismiss one episode's AI suggestions. Send `accept_keys` (item keys from `GET /v1/shows/{show_id}/cluster-suggestions`) and/or `accept_all_sure=true`, or `dismiss=true`, never both. Accepted posts are added to the episode's cluster (created when missing); dismiss drops every remaining suggestion. Unknown keys are an error listing the valid ones.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"accept_keys":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"accept_all_sure":{"default":false,"type":"boolean"},"dismiss":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"cluster_suggestion_review","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/paAtKPJGo56md5VyoEQ9Las7qahL/clusters/cluster-0y0HEJ0OVF7EYdXAvD5ghY","id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","method":"http","written":{"episodeId":"0y0HEJ0OVF7EYdXAvD5ghY","acceptKeys":["tiktok:7421"]},"warnings":[],"urls":{"app":null,"public":null},"error":null,"data":{"accepted":[{"key":"tiktok:7421","platform":"TikTok","url":"https://www.tiktok.com/@caseymorgan66/video/8564"}],"cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions/EPISODE_ID/review\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions/EPISODE_ID/review\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/cluster-suggestions/EPISODE_ID/review\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns":{"get":{"operationId":"list_campaigns","summary":"List campaigns","tags":["Campaigns"],"parameters":[{"name":"status","in":"query","required":false,"schema":{"default":"all","enum":["all","upcoming","active","completed"],"type":"string"},"description":"Status filter or value."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Brand name or slug filter."},{"name":"show_ids","in":"query","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"style":"form","explode":true,"description":"Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"unlinked_only","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"name":"sort_by","in":"query","required":false,"schema":{"default":"startDate:desc","type":"string"},"description":"Sort field."},{"name":"precision","in":"query","required":false,"schema":{"default":"summary","enum":["summary","nodes"],"type":"string"},"description":"summary (fast, stored totals) or a more precise, slower computation."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The workspace's campaigns as the Campaigns page lists them: status, flight, goal progress, pacing, slots, reach by category and format, expected and delivered CPM, EMV, budget, unlinked slots, brand and public URL.\n\n`status` filters after `meta.status_counts` are taken; `brand` matches name or slug; `show_ids` keeps campaigns with a slot or cluster on those shows; `search` matches title, brand and show names; `sort_by` is `<key>:<asc|desc>` (keys: startDate, endDate, status, createdAt, updatedAt, title, brand, reach, goal, pacing, cpm, budget, show). `precision=summary` (default) reads stored cluster summaries, fast but EMV, first-30-days and delivered CPM skip summary-only clusters; `precision=nodes` loads every linked cluster (slow on large networks).\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CampaignRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"campaign"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"status_counts":{"additionalProperties":{"type":"integer"},"description":"Counts before the status filter (like the page chips).","title":"Status Counts","type":"object"},"brands":{"description":"Every brand name across the workspace's campaigns.","items":{"type":"string"},"title":"Brands","type":"array"},"unlinked_count":{"default":0,"description":"Campaigns with at least one unlinked slot (before filters).","title":"Unlinked Count","type":"integer"},"duplicate_count":{"default":0,"title":"Duplicate Count","type":"integer"},"totals":{"additionalProperties":true,"description":"Sums over the filtered rows: reach, budget, expected impressions, EMV.","title":"Totals","type":"object"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"sort_by":{"title":"Sort By","type":"string"},"precision":{"description":"'summary' rows use stored cluster summaries; 'nodes' loaded every linked cluster.","enum":["summary","nodes","none"],"title":"Precision","type":"string"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/campaigns","data":[{"object":"campaign","id":"B9GpElnJc2UQ1JLfav8j","title":"Wonka Snacks — Q4 Push","description":"","status":"active","status_label":"Active","status_is_manual":false,"start_date":"2026-10-01","end_date":"2026-10-31","start_is_fallback":false,"days_remaining":17,"days_until_start":-13,"timing":"17 days left","brand":{"name":"Listener.com","slug":"listener-com","domain":"listener.com","logo":"https://images.example.com/listener/785e0a7080216ca9.png","notes":null,"has_contact":false,"page_url":"https://network.listener.com/northwind-audio/brands/listener-com"},"goals":{"total_views":500000.0,"show_goals":{"paAtKPJGo56md5VyoEQ9Las7qahL":500000},"total_budget":100000.0,"show_budgets":{},"platform_goals":{}},"has_goal":true,"goal_progress_pct":4.9836,"pacing":{"total_slots":3,"live_slots":3,"expected_reach":140728.0,"pacing_pct":28.145599999999998,"delta":-115810.0,"delta_pct":-82.29350235916093,"has_live_pacing":true,"is_ahead":false,"status_label":"Behind","bar_pct":28.145599999999998},"budget":100000.0,"expected_impressions":140728.0,"expected_cpm":710.5906429424138,"delivered_cpm":0.0,"delivered_cpm_status":"measuring","delivered_cpm_long_form":1775.7086559742554,"delivered_cpm_short_form":4651.941203974333,"emv_total":912.78,"emv_enabled":true,"reach":{"total":24918.0,"youtube":20443.0,"youtube_long_form":3850.0,"youtube_shorts":16593.0,"audio":1311.0,"social":3164.0,"long_form":5534.0,"short_form":19384.0,"cluster_long_form":5534.0,"cluster_short_form":19384.0,"long_form_count":4,"short_form_count":8,"clips":12,"posts":0},"engagement":735.0,"engagement_rate":2.949674933782808,"linked_show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","HTSVG2lSc1RmPELJNtCnvOEb4Z2u"],"linked_show_names":["Hard Court","Fourth Quarter"],"show_count":2,"total_slots":3,"linked_slots":3,"unlinked_slot_count":0,"live_slots":3,"cluster_count":3,"clusters_missing":[],"air_checks_detected":0,"duplicate_of":null,"precision":"nodes","warnings":[],"public_url":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j","app_url":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_at":"2026-08-20T15:33:35.789Z","updated_at":"2026-10-07T17:00:55.475Z"},{"object":"campaign","id":"5dnZczrPhPUcJ2Df1eLB","title":"Cyberdyne Fitness — Season Opener","description":"","status":"completed","status_label":"Completed","status_is_manual":true,"start_date":"2026-08-21","end_date":null,"start_is_fallback":true,"days_remaining":null,"days_until_start":-54,"timing":"Marked completed","brand":{"name":"Vandelay Imports","slug":null,"domain":null,"logo":null,"notes":null,"has_contact":false,"page_url":null},"goals":{"total_views":0.0,"show_goals":{},"total_budget":0.0,"show_budgets":{},"platform_goals":{}},"has_goal":false,"goal_progress_pct":null,"pacing":{"total_slots":0,"live_slots":0,"expected_reach":0.0,"pacing_pct":0.0,"delta":0.0,"delta_pct":null,"has_live_pacing":false,"is_ahead":true,"status_label":"No goal","bar_pct":0.0},"budget":0.0,"expected_impressions":0.0,"expected_cpm":0.0,"delivered_cpm":0.0,"delivered_cpm_status":"unavailable","delivered_cpm_long_form":0.0,"delivered_cpm_short_form":0.0,"emv_total":0.0,"emv_enabled":false,"reach":{"total":0.0,"youtube":0.0,"youtube_long_form":0.0,"youtube_shorts":0.0,"audio":0.0,"social":0.0,"long_form":0.0,"short_form":0.0,"cluster_long_form":0.0,"cluster_short_form":0.0,"long_form_count":0,"short_form_count":0,"clips":0,"posts":0},"engagement":0.0,"engagement_rate":0.0,"linked_show_ids":[],"linked_show_names":[],"show_count":0,"total_slots":0,"linked_slots":0,"unlinked_slot_count":0,"live_slots":0,"cluster_count":0,"clusters_missing":[],"air_checks_detected":0,"duplicate_of":null,"precision":"none","warnings":[],"public_url":"https://network.listener.com/northwind-audio/campaigns/5dnZczrPhPUcJ2Df1eLB","app_url":"https://network.listener.com/app/campaign?id=5dnZczrPhPUcJ2Df1eLB&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_at":"2026-08-21T15:14:02.174Z","updated_at":"2026-09-07T20:56:58.158Z"}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"status_counts":{"all":21,"active":20,"upcoming":0,"completed":1},"brands":["Acme Coffee","Umbrella Energy"],"unlinked_count":12,"duplicate_count":2,"totals":{"reach_total":806568,"reach_youtube":314345,"reach_audio":239374,"reach_social":252849,"reach_long_form":396828,"reach_short_form":409740,"budget":361000,"expected_impressions":8281369,"emv_total":25372.500000000004,"slots":71,"linked_slots":31,"unlinked_slots":40,"campaigns":21},"filters":{"status":"all","brand":null,"show_ids":null,"search":null,"unlinked_only":false},"sort_by":"startDate:desc","precision":"nodes","missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:24.302850+00:00","cache_age_seconds":18.8,"note":null,"total":21}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/campaigns\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/campaigns\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"create_campaign","summary":"Create a campaign","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Create a campaign. At least one show must be referenced through `show_goals`, `show_budgets` or `planned_episodes`. Dates are `YYYY-MM-DD` and `end_date` must not precede `start_date`. When `brand.name` is set the brand profile is created or updated first and campaigns already sharing that brand get its details re-stamped (listed in `warnings`). A duplicate title + brand is a warning, not an error. No emails or notifications are sent.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title."},"description":{"default":"","type":"string","description":"Free-text description."},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},"brand":{"anyOf":[{"$ref":"#/components/schemas/BrandInput"},{"type":"null"}],"default":null,"description":"Brand name or slug filter."},"show_goals":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-show view goals: {show_id: views}."},"show_budgets":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-show budgets in dollars: {show_id: amount}."},"total_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Total campaign budget in dollars."},"platform_goals":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-platform goals: {platform: views}."},"planned_episodes":{"anyOf":[{"items":{"$ref":"#/components/schemas/PlannedEpisodeInput"},"type":"array"},{"type":"null"}],"default":null,"description":"Campaign slots: [{show_id, title?, expected_impressions?, budget?}]."},"show_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Limit to these show ids (default: every show in the workspace)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["title"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/wJ7WendsjngdnLGuGoXa","id":"wJ7WendsjngdnLGuGoXa","method":"add","written":{"title":"Soylent Foods — Spring Launch","description":"","startDate":null,"endDate":null,"brandDetails":{"name":"Vandelay Imports","logo":"","domain":"","contact":"","inviteEmail":"","notes":""},"goals":{"totalViews":1000,"showGoals":{"i3KlnFag2DgIpykraVxjrIZwJYcL":1000},"totalBudget":0,"showBudgets":{}},"clusterIds":[],"plannedEpisodes":[],"createdAt":"<serverTimestamp>","updatedAt":"<serverTimestamp>","createdVia":"mcp"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=wJ7WendsjngdnLGuGoXa&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/wJ7WendsjngdnLGuGoXa"},"error":null,"data":{"campaign_id":"wJ7WendsjngdnLGuGoXa","eligible_show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"brand_slug":null},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/campaigns\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\": \"TITLE\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"title\": \"TITLE\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/campaigns\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'title': 'TITLE', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}":{"get":{"operationId":"get_campaign","summary":"Retrieve a campaign","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"activity_limit","in":"query","required":false,"schema":{"default":30,"maximum":200,"minimum":0,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One campaign in full: headline KPIs (reach by category and format, engagement, expected vs delivered CPM, EMV with resolved settings, first-30-days estimate), fulfilment against goal and pacing, every slot with its linked cluster's reach, per-show breakdown, air-check summary, share settings, brand, activity log and URLs. Node-precise: every linked cluster is loaded.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetCampaignResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"campaign"}}}]},"example":{"object":"campaign","id":"B9GpElnJc2UQ1JLfav8j","title":"Wonka Snacks — Q4 Push","description":"","status":"active","status_label":"Active","status_is_manual":false,"status_updated_at":null,"start_date":"2026-10-01","end_date":"2026-10-31","start_is_fallback":false,"days_remaining":17,"days_until_start":-13,"timing":"17 days left","brand":{"name":"Listener.com","slug":"listener-com","domain":"listener.com","logo":"https://images.example.com/listener/785e0a7080216ca9.png","notes":null,"has_contact":false,"page_url":"https://network.listener.com/northwind-audio/brands/listener-com"},"goals":{"total_views":500000.0,"show_goals":{"paAtKPJGo56md5VyoEQ9Las7qahL":500000},"total_budget":100000.0,"show_budgets":{},"platform_goals":{}},"has_goal":true,"goal_progress_pct":29.486400000000003,"goal_progress_clamped_pct":29.486400000000003,"pacing":{"total_slots":3,"live_slots":3,"expected_reach":140728.0,"pacing_pct":28.145599999999998,"delta":6704.0,"delta_pct":4.763799670285942,"has_live_pacing":true,"is_ahead":true,"status_label":"Ahead","bar_pct":28.145599999999998},"budget":100000.0,"slot_budget_total":100000.0,"expected_impressions":140728.0,"expected_cpm":710.5906429424138,"delivered_cpm":678.278799717836,"delivered_cpm_status":"reported","delivered_cpm_detail":{"cpm":678.278799717836,"budget":100000.0,"delivered_impressions":147432.0,"expected_impressions":140728.0,"delivered_slots":3,"total_slots":3,"delivery_pct":104.76379967028595,"is_provisional":false},"format_cpm":{"total_budget":100000.0,"expected_impressions":{"long_form":9993.341991319874,"short_form":130734.65800868013,"total":140728.0},"delivered_impressions":{"long_form":12338.0,"short_form":135094.0,"total":147432.0},"budget_allocation":{"long_form":7101.1753107554105,"short_form":92898.82468924459},"expected_cpm":{"long_form":710.5906429424138,"short_form":710.5906429424138},"delivered_cpm":{"long_form":575.5531942580168,"short_form":687.6606265951455}},"emv":{"enabled":true,"total":88645.58,"impression_value":3010.3300000000004,"engagement_value":85635.25,"like_value":79599.0,"comment_value":6036.25,"impressions":{"long_form":12338.0,"short_form":135094.0,"total":147432.0},"value_by_format":{"long_form":308.45,"short_form":2701.88},"engagement":{"likes":318396.0,"comments":4829.0},"nodes":18,"settings":{"long_form_cpm":25,"short_form_cpm":20,"like_rate":0.25,"comment_rate":1.25,"include_long_form":true,"include_short_form":true,"include_likes":true,"include_comments":true,"show_overrides":{}},"settings_source":"campaign"},"reach":{"total":147432.0,"youtube":20486.0,"youtube_long_form":3850.0,"youtube_shorts":16636.0,"audio":8115.0,"social":118831.0,"long_form":12338.0,"short_form":135094.0,"cluster_long_form":12338.0,"cluster_short_form":135094.0,"long_form_count":5,"short_form_count":12,"clips":17,"posts":0},"engagement":759.0,"engagement_rate":0.5148136089858375,"first_30_days":{"available":true,"reason":null,"dated_count":18,"total_count":18,"undated_with_metrics_count":0,"metrics":{"youtube_reach":18000,"youtube_long_form_reach":2695,"youtube_shorts_reach":15305,"audio_reach":5681,"social_reach":109242,"total_reach":132923,"long_form_reach":8637,"short_form_reach":124286,"long_form_count":5,"short_form_count":12,"total_engagement":663,"engagement_rate":0.4987850108709554,"clips":17,"posts":0},"long_form_share":0.7,"short_form_share":0.92},"linked_show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL"],"linked_show_names":["Hard Court"],"show_count":1,"cluster_ids":["cluster-4uzlgvt6p8QekbVvYkGnbh","cluster-80WiH0Qs4iCPC3OLgg4Xy9"],"clusters_loaded":3,"clusters_missing":[],"total_slots":3,"linked_slots":3,"unlinked_slot_count":0,"live_slots":3,"slots":[{"id":"ep_6503898273889_tgolj5","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_name":"Hard Court","title":"Wayne Motors — Spring Launch","slot_number":1,"expected_impressions":268.0,"expected_impressions_estimated":false,"budget":190.44,"budget_pinned":false,"impressions_pinned":true,"linked_cluster_id":"cluster-4uzlgvt6p8QekbVvYkGnbh","linked_cluster_name":"Coaching hot seat check-in","linked_cluster_loaded":true,"is_live":true,"cluster_reach":{"total_reach":2191,"youtube_reach":2191,"audio_reach":0,"social_reach":0,"long_form_reach":2191,"short_form_reach":0,"clips":1,"posts":0,"precision":"nodes"},"cluster_public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-4uzlgvt6p8QekbVvYkGnbh","fulfillment_pct":817.5373134328358,"excluded_node_count":0},{"id":"ep_6503898273889_psqwbn","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_name":"Hard Court","title":"Cyberdyne Fitness — Season Opener","slot_number":2,"expected_impressions":3227.0,"expected_impressions_estimated":false,"budget":2293.08,"budget_pinned":false,"impressions_pinned":true,"linked_cluster_id":"cluster-80WiH0Qs4iCPC3OLgg4Xy9","linked_cluster_name":"Coaching hot seat check-in","linked_cluster_loaded":true,"is_live":true,"cluster_reach":{"total_reach":3560,"youtube_reach":1659,"audio_reach":0,"social_reach":1901,"long_form_reach":1659,"short_form_reach":1901,"clips":2,"posts":0,"precision":"nodes"},"cluster_public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-80WiH0Qs4iCPC3OLgg4Xy9","fulfillment_pct":110.319181902696,"excluded_node_count":0}],"show_breakdown":[{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","public_url":"https://listener.com/hard-court","metrics":{"youtube_reach":20486,"youtube_long_form_reach":3850,"youtube_shorts_reach":16636,"audio_reach":8115,"social_reach":118831,"total_reach":147432,"long_form_reach":12338,"short_form_reach":135094,"long_form_count":5,"short_form_count":12,"total_engagement":759,"engagement_rate":0.5148136089858375,"clips":17,"posts":0},"slots":3,"linked_slots":3,"live_slots":3,"pacing_expected_reach":140728.0,"delta_from_pacing":6704.0,"reach_goal":500000.0,"fulfillment_pct":29.486400000000003,"precision":"nodes"}],"air_checks":{"has_air_checks":true,"youtube_videos_analyzed":2,"audio_episodes_analyzed":2,"youtube_analyzed_at":"2026-10-10T11:54:45.386000+00:00","audio_analyzed_at":"2026-10-12T17:51:26.859000+00:00","mentions_detected":0,"rss_url":null,"custom_brands":[],"excluded_show_ids":[],"excluded_placement_cluster_ids":[],"exclusions_count":0},"excluded_node_count":0,"excluded_node_ids_count":0,"featured_content_node_id":null,"merged_from":null,"copied_from":null,"created_via":null,"duplicate":null,"share":{"metric_keys":["hero_total_reach","hero_video"],"sm":"","fc":true,"featured_content_node_id":null,"available_metric_keys":["hero_total_reach","hero_video"],"presets":{"all":"","brand-safe":"mtg27","summary":"mnvf3"},"public_url":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"activity_log":{"events":[{"type":"flight","key":"flight-end","day":"2026-10-31","at":"2026-10-31T00:00:00.000Z","platform":null,"title":null,"show_id":null,"show_name":null,"show_names":[],"cluster_id":null,"is_first":null,"clip_count":0,"post_count":0,"views":0.0,"count_label":null,"label":"Flight ends","upcoming":true},{"type":"flight","key":"flight-start","day":"2026-10-01","at":"2026-10-01T00:00:00.000Z","platform":null,"title":null,"show_id":null,"show_name":null,"show_names":[],"cluster_id":null,"is_first":null,"clip_count":0,"post_count":0,"views":0.0,"count_label":null,"label":"Flight started","upcoming":false}],"total_events":21,"summary":{"total_slots":3,"linked_slots":3,"unlinked_slots":0,"released_episodes":3,"content_pieces":17}},"public_url":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j","app_url":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_at":"2026-08-20T15:33:35.789Z","updated_at":"2026-10-07T17:00:55.475Z","precision":"nodes","warnings":[],"computed_at":"2026-10-14T17:34:24.909341+00:00","cache_age_seconds":19.4,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"patch":{"operationId":"update_campaign","summary":"Update a campaign","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Update a campaign's title, description, dates, brand, goals, budgets, EMV settings or featured content. Only the fields you send change. `brand` fields merge into the campaign's brand; `show_goals` replaces the per-show goals and recomputes the total; `emv_settings` merges and is normalised. Renaming the brand re-stamps other campaigns of that brand (listed in `warnings`). `clear_featured_content_node` / `clear_platform_goals` remove those fields. Slots, cluster links and status have their own endpoints.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Title."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Free-text description."},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},"brand":{"anyOf":[{"$ref":"#/components/schemas/BrandInput"},{"type":"null"}],"default":null,"description":"Brand name or slug filter."},"show_goals":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-show view goals: {show_id: views}."},"show_budgets":{"anyOf":[{"additionalProperties":{"type":"number"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-show budgets in dollars: {show_id: amount}."},"total_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Total campaign budget in dollars."},"platform_goals":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"description":"Per-platform goals: {platform: views}."},"emv_settings":{"anyOf":[{"$ref":"#/components/schemas/EmvSettingsInput"},{"type":"null"}],"default":null},"featured_content_node_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"clear_featured_content_node":{"default":false,"type":"boolean"},"clear_platform_goals":{"default":false,"type":"boolean"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"update","written":{"description":"A deep dive into the numbers behind the season so far.","updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","brand_slug":null},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]},"delete":{"operationId":"delete_campaign","summary":"Delete a campaign","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"name":"confirm","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Permanently delete a campaign (no undo, no cascade) and report what it leaves behind: pending brand invites and shared reports that embed it. Send `?dry_run=true` first to see them.\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `?confirm=true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `campaigns:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"delete","written":{"deleted":true,"campaign":{"id":"B9GpElnJc2UQ1JLfav8j","title":"Wonka Snacks — Q4 Push","slots":3},"orphans":{"brand_invite_ids":["brand_B9GpElnJc2UQ1JLfav8j_casey_brand1_listener_com"],"shared_report_ids":[]}},"warnings":["1 brand invite(s) will stay 'pending' forever: brand_B9GpElnJc2UQ1JLfav8j_casey_brand1_listener_com."],"urls":{"app":"https://network.listener.com/app/campaigns?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":null},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","orphans":{"brand_invite_ids":["brand_B9GpElnJc2UQ1JLfav8j_casey_brand1_listener_com"],"shared_report_ids":[]},"confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/timeline":{"get":{"operationId":"get_campaign_timeline","summary":"Campaign timeline","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"window","in":"query","required":false,"schema":{"default":"30d","enum":["7d","30d","90d","all"],"type":"string"},"description":"Reporting window."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"First day, YYYY-MM-DD (inclusive). With end_date, overrides time_range."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Last day, YYYY-MM-DD (inclusive). With start_date, overrides time_range."},{"name":"chart_type","in":"query","required":false,"schema":{"default":"cumulative","enum":["daily","cumulative"],"type":"string"},"description":"daily values or a cumulative running total."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"A campaign's reach series (total, audio, YouTube, social; daily buckets as the campaign chart draws them) and its EMV accrual over a window. `window` is `7d`, `30d`, `90d` or `all`, or send `start_date` + `end_date`; `chart_type` is `daily` or `cumulative`. EMV points are thinned to at most 180 by summing whole weeks.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetCampaignTimelineResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"campaign_timeline"}}}]},"example":{"object":"campaign_timeline","campaign_id":"B9GpElnJc2UQ1JLfav8j","title":"Wonka Snacks — Q4 Push","window":{"time_range":"30d","chart_type":"cumulative","start":"2026-09-15","end":"2026-10-14","previous_start":"2026-08-16","previous_end":"2026-09-14"},"chart_type":"cumulative","totals":{"total_reach":0.0,"audio_reach":0.0,"youtube_reach":0.0,"social_reach":0.0},"growth":{"total_reach":-100.0,"audio_reach":0.0,"youtube_reach":-100.0,"social_reach":0.0},"reach_series":[{"day":"2026-09-15","date":"Sep 15","value":0.0},{"day":"2026-09-16","date":"Sep 16","value":0.0}],"audio_series":[{"day":"2026-09-15","date":"Sep 15","value":0.0},{"day":"2026-09-16","date":"Sep 16","value":0.0}],"youtube_series":[{"day":"2026-09-15","date":"Sep 15","value":0.0},{"day":"2026-09-16","date":"Sep 16","value":0.0}],"social_series":[{"day":"2026-09-15","date":"Sep 15","value":0.0},{"day":"2026-09-16","date":"Sep 16","value":0.0}],"events_counted":17,"emv_series":[{"day":"2026-09-15","date":"Sep 15","emv":88600.05256129433,"period_emv":2.8482813043228816,"emv_by_platform":{"YouTube":151.40882228633853,"Instagram":2321.8376718143772,"Spotify":202.76501577920686,"Facebook":61.49992830113916,"YouTube Shorts":606.9699356133888,"X":85241.5,"TikTok":14.071187499887778},"period_emv_by_platform":{"YouTube":2.6398200198562165,"Instagram":0.19506094488315284,"Spotify":0.006698907672415544,"Facebook":6.968743882396211e-06,"YouTube Shorts":6.258032499317778e-06,"X":0.0,"TikTok":0.006688205135725767}},{"day":"2026-09-16","date":"Sep 16","emv":88602.78044605965,"period_emv":2.7278847653215053,"emv_by_platform":{"YouTube":153.94479762931465,"Instagram":2322.01698551974,"Spotify":202.7714511666781,"Facebook":61.49993470719671,"YouTube Shorts":606.969941366121,"X":85241.5,"TikTok":14.077335670601867},"period_emv_by_platform":{"YouTube":2.5359753429761156,"Instagram":0.17931370536280156,"Spotify":0.006435387471242393,"Facebook":6.406057551089361e-06,"YouTube Shorts":5.752732249675319e-06,"X":0.0,"TikTok":0.006148170714089574}}],"emv_total":88645.58,"emv_by_platform":{"YouTube":194.75,"Instagram":2323.8450000000003,"Spotify":202.875,"Facebook":61.5,"YouTube Shorts":606.9699999999999,"X":85241.5,"TikTok":14.14},"emv_enabled":true,"emv_nodes_counted":18,"emv_points_thinned":false,"precision":"nodes","warnings":[],"public_url":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j","computed_at":"2026-10-14T17:34:27.073407+00:00","cache_age_seconds":21.5,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/timeline\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/timeline\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/timeline\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/cpm-insights":{"get":{"operationId":"get_campaign_cpm_insights","summary":"Campaign CPM insights","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"peer_limit","in":"query","required":false,"schema":{"default":24,"maximum":60,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"A campaign's expected vs delivered CPM per format and where it sits against the workspace's recent campaigns (median of the 12 most recent peers with a delivered CPM; within ±3 % counts as in line). Peers are the `peer_limit` most recently updated other campaigns, loaded at node precision. Delivered CPM is null until a campaign has delivered at least 25 % of its expected impressions.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetCampaignCpmInsightsResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"campaign_cpm_insights"}}}]},"example":{"object":"campaign_cpm_insights","campaign_id":"B9GpElnJc2UQ1JLfav8j","title":"Wonka Snacks — Q4 Push","expected_cpm":710.5906429424138,"delivered_cpm":678.278799717836,"delivered_cpm_status":"reported","delivered_cpm_detail":{"cpm":678.278799717836,"budget":100000.0,"delivered_impressions":147432.0,"expected_impressions":140728.0,"delivered_slots":3,"total_slots":3,"delivery_pct":104.76379967028595,"is_provisional":false},"format_cpm":{"total_budget":100000.0,"expected_impressions":{"long_form":9993.341991319874,"short_form":130734.65800868013,"total":140728.0},"delivered_impressions":{"long_form":12338.0,"short_form":135094.0,"total":147432.0},"budget_allocation":{"long_form":7101.1753107554105,"short_form":92898.82468924459},"expected_cpm":{"long_form":710.5906429424138,"short_form":710.5906429424138},"delivered_cpm":{"long_form":575.5531942580168,"short_form":687.6606265951455}},"benchmarks":{"long_form":{"current_cpm":575.5531942580168,"median_cpm":104.068522482916,"delta_pct":453.0,"signed_delta_pct":453.0521434591331,"direction":"above","sample_size":3,"label":"453% above recent median","is_renderable":true},"short_form":{"current_cpm":687.6606265951455,"median_cpm":126.79834712338442,"delta_pct":442.0,"signed_delta_pct":442.32617553444874,"direction":"above","sample_size":3,"label":"442% above recent median","is_renderable":true}},"peers":[{"id":"dfEUh5kkZU1O7vAkaMYK","title":"Cyberdyne Fitness — Season Opener","status":"active","brand":"Umbrella Energy","updated_at":"2026-09-29T17:32:28.239Z","delivered_cpm":125.1112099644128,"delivered_cpm_status":"reported","delivered_cpm_long_form":104.068522482916,"delivered_cpm_short_form":126.79834712338442,"expected_cpm":130.90813884989927,"precision":"nodes"},{"id":"sdwY3BeF2mVbCDIqsM6u","title":"Vandelay Imports — Q4 Push","status":"active","brand":"Acme Coffee","updated_at":"2026-09-25T01:44:15.349Z","delivered_cpm":273.993757924024,"delivered_cpm_status":"reported","delivered_cpm_long_form":1036.9049105085603,"delivered_cpm_short_form":186.43648177325696,"expected_cpm":100.0,"precision":"nodes"}],"peers_considered":20,"peers_with_cpm":{"long_form":3,"short_form":3},"workspace_campaign_count":21,"precision":"nodes","warnings":[],"public_url":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j","computed_at":"2026-10-14T17:34:27.089408+00:00","cache_age_seconds":21.6,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/cpm-insights\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/cpm-insights\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/cpm-insights\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/status":{"post":{"operationId":"set_campaign_status","summary":"Set a campaign's status","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set a campaign's manual status (`upcoming`, `active`, `completed`), or send `\"status\": null` to clear the override so the status follows the dates again. No other side effects.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"anyOf":[{"enum":["upcoming","active","completed"],"type":"string"},{"type":"null"}],"default":null,"description":"Status filter or value."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"update","written":{"status":"active","statusUpdatedAt":"<serverTimestamp>","updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","status":"active"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/status\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/status\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/status\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/slots":{"post":{"operationId":"add_campaign_planned_episodes","summary":"Add campaign slots","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Append slots (planned episodes) to a campaign: a show plus optional `title`, `expected_impressions`, `budget` and `linked_cluster_id` each. Returns the new slot ids and the full slot list. A cluster already linked to another slot is refused (single-slot rule); up to 2,000 slots per campaign.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"planned_episodes":{"items":{"$ref":"#/components/schemas/PlannedEpisodeInput"},"maxItems":200,"minItems":1,"type":"array","description":"Campaign slots: [{show_id, title?, expected_impressions?, budget?}]."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["planned_episodes"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"transaction","written":{"plannedEpisodes":[{"impressionsPinned":true,"budget":190.44,"id":"ep_6503898273889_tgolj5","linkedClusterId":"cluster-4uzlgvt6p8QekbVvYkGnbh","title":"Wayne Motors — Spring Launch","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":268},{"impressionsPinned":true,"budget":2293.08,"id":"ep_6503898273889_psqwbn","linkedClusterId":"cluster-80WiH0Qs4iCPC3OLgg4Xy9","title":"Cyberdyne Fitness — Season Opener","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":3227}],"clusterIds":["cluster-4uzlgvt6p8QekbVvYkGnbh","cluster-80WiH0Qs4iCPC3OLgg4Xy9"],"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","added_slot_ids":["ep_2585703747213_7iep6b"]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"planned_episodes\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"planned_episodes\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'planned_episodes': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/slots/{slot_id}":{"patch":{"operationId":"update_campaign_planned_episode","summary":"Update a campaign slot","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"slot_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign slot (planned episode) id from the campaign's slots."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Edit one slot's `title`, `expected_impressions`, `budget` or `show_id`. Setting impressions or budget pins the value so the app stops auto-distributing it. To change the linked cluster use `PUT` / `DELETE /v1/campaigns/{campaign_id}/slots/{slot_id}/cluster`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Title."},"expected_impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null},"budget":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A show id in this workspace (see GET /v1/shows)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"transaction","written":{"plannedEpisodes":[{"impressionsPinned":true,"budget":190.44,"id":"ep_6503898273889_tgolj5","linkedClusterId":"cluster-4uzlgvt6p8QekbVvYkGnbh","title":"Wayne Motors — Q4 Push","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":268},{"impressionsPinned":true,"budget":2293.08,"id":"ep_6503898273889_psqwbn","linkedClusterId":"cluster-80WiH0Qs4iCPC3OLgg4Xy9","title":"Cyberdyne Fitness — Season Opener","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":3227}],"clusterIds":["cluster-4uzlgvt6p8QekbVvYkGnbh","cluster-80WiH0Qs4iCPC3OLgg4Xy9"],"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","slot_id":"ep_6503898273889_tgolj5"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/slots/{slot_id}/cluster":{"put":{"operationId":"link_cluster_to_campaign","summary":"Link a cluster to a slot","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"slot_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign slot (planned episode) id from the campaign's slots."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Link an existing cluster (`show_id` + `cluster_id`, from `GET /v1/clusters`) to one campaign slot, attributing its reach to the campaign. A cluster already linked to another slot of the same campaign is refused (double-count guard). `included_node_ids` limits which of the cluster's nodes count. The cluster itself is never modified.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cluster_id":{"type":"string","description":"Cluster id (see GET /v1/clusters)."},"show_id":{"type":"string","description":"A show id in this workspace (see GET /v1/shows)."},"included_node_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["cluster_id","show_id"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"transaction","written":{"plannedEpisodes":[{"impressionsPinned":true,"budget":190.44,"id":"ep_6503898273889_tgolj5","linkedClusterId":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","title":"Wayne Motors — Spring Launch","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":268},{"impressionsPinned":true,"budget":2293.08,"id":"ep_6503898273889_psqwbn","linkedClusterId":"cluster-80WiH0Qs4iCPC3OLgg4Xy9","title":"Cyberdyne Fitness — Season Opener","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":3227}],"clusterIds":["cluster-0y0HEJ0OVF7EYdXAvD5ghY","cluster-80WiH0Qs4iCPC3OLgg4Xy9"],"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","slot_id":"ep_6503898273889_tgolj5","cluster_id":"cluster-0y0HEJ0OVF7EYdXAvD5ghY","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","cluster_name":"Five takeaways from the opener"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"cluster_id\": \"CLUSTER_ID\", \"show_id\": \"SHOW_ID\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"cluster_id\": \"CLUSTER_ID\", \"show_id\": \"SHOW_ID\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'cluster_id': 'CLUSTER_ID', 'show_id': 'SHOW_ID', 'dry_run': True},\n)\nprint(resp.json())"}]},"delete":{"operationId":"unlink_cluster_from_campaign","summary":"Unlink a slot's cluster","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"slot_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign slot (planned episode) id from the campaign's slots."},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Detach the linked cluster from one campaign slot without deleting the slot. The cluster itself is never modified.\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"campaign","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaigns/B9GpElnJc2UQ1JLfav8j","id":"B9GpElnJc2UQ1JLfav8j","method":"transaction","written":{"plannedEpisodes":[{"impressionsPinned":true,"budget":190.44,"id":"ep_6503898273889_tgolj5","linkedClusterId":null,"title":"Wayne Motors — Spring Launch","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":268},{"impressionsPinned":true,"budget":2293.08,"id":"ep_6503898273889_psqwbn","linkedClusterId":"cluster-80WiH0Qs4iCPC3OLgg4Xy9","title":"Cyberdyne Fitness — Season Opener","showId":"paAtKPJGo56md5VyoEQ9Las7qahL","budgetPinned":false,"expectedImpressions":3227}],"clusterIds":["cluster-80WiH0Qs4iCPC3OLgg4Xy9","cluster-1xwmdkckUe29biQhmpMkx9"],"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=B9GpElnJc2UQ1JLfav8j&uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/campaigns/B9GpElnJc2UQ1JLfav8j"},"error":null,"data":{"campaign_id":"B9GpElnJc2UQ1JLfav8j","slot_id":"ep_6503898273889_tgolj5","previous_cluster_id":"cluster-4uzlgvt6p8QekbVvYkGnbh"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/slots/SLOT_ID/cluster?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/brands":{"get":{"operationId":"list_brands","summary":"List brands","tags":["Campaigns"],"parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"precision","in":"query","required":false,"schema":{"default":"summary","enum":["summary","nodes"],"type":"string"},"description":"summary (fast, stored totals) or a more precise, slower computation."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The workspace's advertisers (brand profiles plus every brand named on a campaign) with campaign counts, status mix, shows reached, aggregated reach, budget and CPM, EMV and the public brand page URL. `search` matches name, slug or domain; `precision=summary` (default) reads stored cluster summaries, `nodes` loads every linked cluster.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/BrandRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"brand"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/brands","data":[{"object":"brand","slug":"acme-coffee","name":"Acme Coffee","normalized_name":"acme coffee","domain":"acme-coffee.example.com","logo":"https://www.example.com/b23436f3","notes":null,"has_contact":false,"has_brand_doc":true,"campaign_ids":["sdwY3BeF2mVbCDIqsM6u","YaVU05YMJcmX4k5uRGkM"],"campaign_count":2,"status_counts":{"active":2},"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"show_count":5,"last_used_at":"2026-09-25T01:44:15.349Z","totals":{"total_reach":278955,"audio_reach":63296,"youtube_reach":106020,"social_reach":109639,"long_form_reach":140352,"short_form_reach":138603,"budget":200000,"planned_impressions":2000000,"planned_slots":17,"linked_slots":8,"expected_cpm":100,"delivered_cpm":394.3288343998136,"delivered_cpm_status":"reported","delivered_cpm_budget":110000,"delivered_cpm_impressions":278955,"delivered_cpm_delivery_pct":25.359545454545458,"delivered_cpm_campaigns":1,"delivery_rate":13.947750000000001,"campaign_count":2,"show_count":5},"emv_total":8765.86,"precision":"nodes","public_url":"https://network.listener.com/northwind-audio/brands/acme-coffee","app_url":"https://network.listener.com/app/campaigns?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78"},{"object":"brand","slug":"globex-sports","name":"Globex Sports","normalized_name":"globex-sports","domain":"globex-sports.example.com","logo":"https://www.example.com/cd0528ea","notes":null,"has_contact":false,"has_brand_doc":true,"campaign_ids":["IbnWq9HETdVekDCCNnYu","5BUeGDiYfhlbz5NrFLmt"],"campaign_count":2,"status_counts":{"active":2},"show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"show_count":3,"last_used_at":"2026-09-15T15:53:50.428Z","totals":{"total_reach":0,"audio_reach":0,"youtube_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"budget":15000,"planned_impressions":900000,"planned_slots":8,"linked_slots":1,"expected_cpm":16.666666666666668,"delivered_cpm":0,"delivered_cpm_status":"measuring","delivered_cpm_budget":0,"delivered_cpm_impressions":0,"delivered_cpm_delivery_pct":null,"delivered_cpm_campaigns":0,"delivery_rate":0,"campaign_count":2,"show_count":3},"emv_total":0.0,"precision":"nodes","public_url":"https://network.listener.com/northwind-audio/brands/globex-sports","app_url":"https://network.listener.com/app/campaigns?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78"}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"filters":{"search":null},"precision":"nodes","computed_at":"2026-10-14T17:34:29.929160+00:00","cache_age_seconds":24.4,"note":null,"total":8}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/brands\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/brands\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/brands\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/brands/{brand_slug}":{"get":{"operationId":"get_brand","summary":"Retrieve a brand","tags":["Campaigns"],"parameters":[{"name":"brand_slug","in":"path","required":true,"schema":{"type":"string"},"description":"Brand slug (see GET /v1/brands)."},{"name":"time_range","in":"query","required":false,"schema":{"default":"all","enum":["7d","30d","90d","all"],"type":"string"},"description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},{"name":"chart_type","in":"query","required":false,"schema":{"default":"cumulative","enum":["daily","cumulative"],"type":"string"},"description":"daily values or a cumulative running total."},{"name":"precision","in":"query","required":false,"schema":{"default":"nodes","enum":["summary","nodes"],"type":"string"},"description":"summary (fast, stored totals) or a more precise, slower computation."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One brand's report as its public page computes it: totals (reach by category, budget, planned impressions, expected and delivered CPM), per-campaign rows, per-show performance, EMV, invites and a reach trend. The path also accepts the brand name. `time_range` (`7d`, `30d`, `90d`, `all`) and `chart_type` shape the trend; `precision=nodes` (default) loads every linked cluster, `summary` is faster but skips EMV.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetBrandResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"brand"}}}]},"example":{"object":"brand","slug":"acme-coffee","name":"Acme Coffee","domain":"acme-coffee.example.com","logo":"https://www.example.com/b23436f3","notes":null,"has_contact":false,"has_brand_doc":true,"brand_doc":{"logo":"https://www.example.com/b23436f3","domain":"acme-coffee.example.com","name":"Acme Coffee","notes":"","updatedAt":"2026-08-19T14:20:56.683Z","createdAt":"2026-08-19T14:20:56.683Z","normalizedName":"acme coffee","slug":"acme-coffee"},"invites":[{"id":"brand_sdwY3BeF2mVbCDIqsM6u_vic_brands_listener_com","brand_name":"Acme Coffee","campaign_id":"sdwY3BeF2mVbCDIqsM6u","campaign_title":"Vandelay Imports — Q4 Push","status":"pending","invite_email_masked":"v***@mxsxmlhkfvuhc15","has_brand_account":false,"created_at":"2026-05-01T17:40:46.864Z","accepted_at":null,"revoked_at":null}],"campaign_ids":["sdwY3BeF2mVbCDIqsM6u","YaVU05YMJcmX4k5uRGkM"],"campaign_count":2,"totals":{"total_reach":401469,"audio_reach":70100,"youtube_reach":106063,"social_reach":225306,"long_form_reach":147156,"short_form_reach":254313,"budget":200000,"planned_impressions":2000000,"planned_slots":17,"linked_slots":8,"expected_cpm":100,"delivered_cpm":273.993757924024,"delivered_cpm_status":"reported","delivered_cpm_budget":110000,"delivered_cpm_impressions":401469,"delivered_cpm_delivery_pct":36.497181818181815,"delivered_cpm_campaigns":1,"delivery_rate":20.07345,"campaign_count":2,"show_count":4},"campaign_rows":[{"id":"sdwY3BeF2mVbCDIqsM6u","title":"Vandelay Imports — Q4 Push","description":"","status":"active","show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"show_names":["Hard Court","The Bullpen"],"show_count":4,"total_reach":401469,"audio_reach":70100,"youtube_reach":106063,"social_reach":225306,"long_form_reach":147156,"short_form_reach":254313,"budget":200000,"planned_impressions":2000000,"expected_cpm":100.0,"delivered_cpm":273.993757924024,"delivered_cpm_status":"reported","delivered_cpm_budget":110000.0,"delivered_cpm_impressions":401469.0,"delivered_cpm_delivery_pct":36.497181818181815,"delivered_cpm_slots":8,"delivery_rate":20.07345,"goal":2000000,"fulfillment_rate":20.07345,"planned_slots":17,"linked_slots":8,"start_at":"2025-11-06T00:00:00.000Z","end_at":"2026-09-10T00:00:00.000Z"},{"id":"YaVU05YMJcmX4k5uRGkM","title":"Initech Insurance — Summer Series","description":"Our hosts react to the weekend's results and look ahead to next week.","status":"active","show_ids":[],"show_names":[],"show_count":0,"total_reach":0,"audio_reach":0,"youtube_reach":0,"social_reach":0,"long_form_reach":0,"short_form_reach":0,"budget":0,"planned_impressions":0,"expected_cpm":0.0,"delivered_cpm":0.0,"delivered_cpm_status":"unavailable","delivered_cpm_budget":0.0,"delivered_cpm_impressions":0.0,"delivered_cpm_delivery_pct":null,"delivered_cpm_slots":0,"delivery_rate":null,"goal":1000000,"fulfillment_rate":0.0,"planned_slots":0,"linked_slots":0,"start_at":"2026-02-04T17:32:33.598Z","end_at":"2026-02-04T17:32:33.598Z"}],"show_performance":[{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","handle":"hard-court","total_reach":311838,"audio_reach":15265,"youtube_reach":94248,"social_reach":202325,"long_form_reach":87070,"short_form_reach":224768,"planned_impressions":500000,"budget":50000,"planned_slots":5,"linked_slots":5,"campaign_ids":["sdwY3BeF2mVbCDIqsM6u"],"campaign_count":1,"expected_cpm":100.0,"delivered_cpm":276.7675761249218,"delivered_cpm_status":"reported","delivered_cpm_budget":50000.0,"delivered_cpm_impressions":180657.0,"delivery_rate":62.3676},{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","handle":"the-bullpen","total_reach":89631,"audio_reach":54835,"youtube_reach":11815,"social_reach":22981,"long_form_reach":60086,"short_form_reach":29545,"planned_impressions":500000,"budget":50000,"planned_slots":2,"linked_slots":2,"campaign_ids":["sdwY3BeF2mVbCDIqsM6u"],"campaign_count":1,"expected_cpm":100.0,"delivered_cpm":295.16461330484015,"delivered_cpm_status":"reported","delivered_cpm_budget":50000.0,"delivered_cpm_impressions":169397.0,"delivery_rate":17.9262}],"shows":[{"id":"paAtKPJGo56md5VyoEQ9Las7qahL","name":"Hard Court","image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","handle":"hard-court"},{"id":"0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","name":"The Bullpen","image":"https://images.example.com/listener/8f6c3c4428259526.jpg","handle":"the-bullpen"}],"emv_total":96498.66,"emv_by_campaign":{"sdwY3BeF2mVbCDIqsM6u":96498.66,"YaVU05YMJcmX4k5uRGkM":0.0},"trend":{"time_range":"all","chart_type":"cumulative","points":[{"total_reach":89408,"audio_reach":54612,"youtube_reach":11815,"social_reach":22981,"long_form_reach":0,"short_form_reach":0,"date":"2025-11-06"},{"total_reach":90900,"audio_reach":54612,"youtube_reach":11815,"social_reach":24473,"long_form_reach":0,"short_form_reach":0,"date":"2026-01-12"}]},"precision":"nodes","public_url":"https://network.listener.com/northwind-audio/brands/acme-coffee","app_url":"https://network.listener.com/app/campaigns?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","computed_at":"2026-10-14T17:34:29.940750+00:00","cache_age_seconds":24.4,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/brands/BRAND_SLUG\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/brands/BRAND_SLUG\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/brands/BRAND_SLUG\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"put":{"operationId":"upsert_campaign_brand","summary":"Create or update a brand","tags":["Campaigns"],"parameters":[{"name":"brand_slug","in":"path","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Create or update a brand profile once for every campaign: name, logo, domain, contact, invite email, notes. Every campaign of the brand gets its brand details re-stamped in the same write; when more than one campaign is affected the request needs `\"confirm\": true` (the 409 preview and a dry run both list `affected_campaign_ids`).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name."},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"contact":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"invite_email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false,"required":["name"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"brand","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/campaignBrands/acme-coffee","id":"acme-coffee","method":"set-merge","written":{"name":"Acme Coffee","logo":"https://www.example.com/b23436f3","domain":"acme-coffee.example.com","contact":"","inviteEmail":"","notes":"","slug":"acme-coffee","normalizedName":"acme coffee","updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaigns?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/northwind-audio/brands/acme-coffee"},"error":null,"data":{"slug":"acme-coffee","brand":{"name":"Acme Coffee","logo":"https://www.example.com/b23436f3","domain":"acme-coffee.example.com","contact":"","inviteEmail":"","notes":"","slug":"acme-coffee"},"affected_campaign_ids":[],"created":false},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/brands/BRAND_SLUG\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"NAME\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/brands/BRAND_SLUG\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"name\": \"NAME\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/brands/BRAND_SLUG\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'name': 'NAME', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/air-checks":{"get":{"operationId":"list_air_checks","summary":"List air checks","tags":["Campaigns"],"parameters":[{"name":"campaign_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"show_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Brand name or slug filter."},{"name":"status","in":"query","required":false,"schema":{"default":"all","enum":["all","detected","missing","pending","blocked","excluded"],"type":"string"},"description":"Status filter or value."},{"name":"platform","in":"query","required":false,"schema":{"anyOf":[{"enum":["spotify","youtube"],"type":"string"},{"type":"null"}],"default":null},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"name":"group_by","in":"query","required":false,"schema":{"anyOf":[{"enum":["advertiser","publisher","campaign","show"],"type":"string"},{"type":"null"}],"default":null},"description":"Group the results by this field."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Ad-read verification rows, one per campaign placement, with status (`detected`, `missing`, `pending`, `blocked`, `excluded`), the transcript-capable targets (Spotify episode, long-form YouTube video), every brand mention found (collapsed into ad reads with YouTube timestamp links) and pre / mid / post placement. `group_by` (`advertiser`, `publisher`, `campaign`, `show`) adds groups in `meta`. Narrow with `campaign_id`, `brand` or `show_id` on large networks.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AirCheckRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"air_check"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"status_counts":{"additionalProperties":{"type":"integer"},"description":"Counts over the filtered rows.","title":"Status Counts","type":"object"},"groups":{"description":"Groups over the filtered rows (all pages) when group_by is set.","items":{"$ref":"#/components/schemas/AirCheckGroup"},"title":"Groups","type":"array"},"group_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Group By"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"campaigns_scanned":{"default":0,"title":"Campaigns Scanned","type":"integer"},"clusters_loaded":{"default":0,"title":"Clusters Loaded","type":"integer"},"clusters_skipped":{"default":0,"description":"Linked clusters beyond the fetch cap (narrow with campaign_id/brand/show_id).","title":"Clusters Skipped","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/air-checks","data":[{"object":"air_check","id":"dfEUh5kkZU1O7vAkaMYK::cluster-4uzlgvt6p8QekbVvYkGnbh","campaign_id":"dfEUh5kkZU1O7vAkaMYK","campaign_title":"Cyberdyne Fitness — Season Opener","campaign_type":"Baked-in","campaign_sub":"","advertiser":"Umbrella Energy","brand_slug":"acmecoffee","brand_logo":"https://images.example.com/listener/a3504ff4873daa28.png","show":"Hard Court","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","publish_date":"2026-08-19T00:00:00.000Z","geo":"US","episode":"Coaching hot seat check-in","episode_id":"4uzlgvt6p8QekbVvYkGnbh","episode_url":"https://open.spotify.com/episode/4uzlgvt6p8QekbVvYkGnbh","cluster_id":"cluster-4uzlgvt6p8QekbVvYkGnbh","cluster_public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-4uzlgvt6p8QekbVvYkGnbh","campaign_public_url":"https://network.listener.com/northwind-audio/campaigns/dfEUh5kkZU1O7vAkaMYK","targets":[{"platform":"spotify","label":"Spotify","id":"4uzlgvt6p8QekbVvYkGnbh","node_id":"episode-4uzlgvt6p8QekbVvYkGnbh","url":"https://open.spotify.com/episode/4uzlgvt6p8QekbVvYkGnbh","title":"Coaching hot seat check-in","duration_seconds":2295.0,"views":0.0,"analyzed":true},{"platform":"youtube","label":"YouTube","id":"EbiTsnaP3Ef","node_id":"clip-3878174953528-5204","url":"https://www.youtube.com/watch?v=EbiTsnaP3Ef","title":"Coaching hot seat check-in","duration_seconds":2296.0,"views":2191.0,"analyzed":true}],"platforms":["spotify","youtube"],"status":"missing","transcript_available":true,"needs_aircheck":false,"is_excluded":false,"scan_blocked_reason":null,"episode_length_seconds":2295.0,"node_reach":0.0,"start_seconds":0.0,"length_seconds":0.0,"location_pct":null,"unit":null,"place_total":null,"group_count":0,"mentions":[],"ad_reads":[]},{"object":"air_check","id":"YTnljcesYENBaua7HG19::cluster-4uzlgvt6p8QekbVvYkGnbh","campaign_id":"YTnljcesYENBaua7HG19","campaign_title":"Acme Coffee — Playoff Run","campaign_type":"Baked-in","campaign_sub":"","advertiser":"Acme Coffee","brand_slug":null,"brand_logo":null,"show":"Hard Court","show_id":"paAtKPJGo56md5VyoEQ9Las7qahL","show_image":"https://images.example.com/listener/6cbd825d3f77ec48.jpg","publish_date":"2026-08-19T00:00:00.000Z","geo":"US","episode":"Coaching hot seat check-in","episode_id":"4uzlgvt6p8QekbVvYkGnbh","episode_url":"https://open.spotify.com/episode/4uzlgvt6p8QekbVvYkGnbh","cluster_id":"cluster-4uzlgvt6p8QekbVvYkGnbh","cluster_public_url":"https://listener.com/cluster/paAtKPJGo56md5VyoEQ9Las7qahL_cluster-4uzlgvt6p8QekbVvYkGnbh","campaign_public_url":"https://network.listener.com/northwind-audio/campaigns/YTnljcesYENBaua7HG19","targets":[{"platform":"spotify","label":"Spotify","id":"4uzlgvt6p8QekbVvYkGnbh","node_id":"episode-4uzlgvt6p8QekbVvYkGnbh","url":"https://open.spotify.com/episode/4uzlgvt6p8QekbVvYkGnbh","title":"Coaching hot seat check-in","duration_seconds":2295.0,"views":0.0,"analyzed":false},{"platform":"youtube","label":"YouTube","id":"EbiTsnaP3Ef","node_id":"clip-3878174953528-5204","url":"https://www.youtube.com/watch?v=EbiTsnaP3Ef","title":"Coaching hot seat check-in","duration_seconds":2296.0,"views":2191.0,"analyzed":false}],"platforms":["spotify","youtube"],"status":"blocked","transcript_available":false,"needs_aircheck":false,"is_excluded":false,"scan_blocked_reason":"This campaign has no brand name, so there is nothing to look for in the transcript. Add a brand to the campaign to make it scannable.","episode_length_seconds":2295.0,"node_reach":0.0,"start_seconds":0.0,"length_seconds":0.0,"location_pct":null,"unit":null,"place_total":null,"group_count":0,"mentions":[],"ad_reads":[]}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"status_counts":{"all":32,"detected":0,"missing":18,"pending":0,"blocked":14,"excluded":0},"groups":[],"group_by":null,"filters":{"campaign_id":null,"show_id":null,"brand":null,"status":"all","platform":null},"campaigns_scanned":21,"clusters_loaded":16,"clusters_skipped":0,"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:30.737422+00:00","cache_age_seconds":25.2,"note":null,"total":32}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/air-checks\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/air-checks\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/air-checks\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/reports":{"get":{"operationId":"list_reports","summary":"List shared reports","tags":["Reports"],"parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Shared reports, newest first, with headline reach numbers, element ids, scope and share URLs. `search` matches title, template id or network name.\n\n- Required scope: `reports:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ReportRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"report"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"kind":{"enum":["reports","templates"],"title":"Kind","type":"string"},"templates":{"items":{"$ref":"#/components/schemas/ReportTemplateRow"},"title":"Templates","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"built_in_template_count":{"default":0,"title":"Built In Template Count","type":"integer"},"custom_template_count":{"default":0,"title":"Custom Template Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/reports","data":[{"object":"report","id":"yDOF1QDhp4fJsSahuI0L","title":"Executive summary","network_name":"Northwind Audio","time_range":"30d","comparison_mode":"previous_period","created_at":"2026-10-14T07:57:01.185000+00:00","updated_at":null,"created_by":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_via":"app","is_automated":false,"is_test":false,"template_id":null,"element_count":0,"element_ids":[],"element_metrics":[],"element_types":{},"report_scope":{"is_single_show":false,"scope_label":"Multiple Shows","detail_text":"13 shows included","show_count":13,"show_ids":["sLLP2LKo9LJHqRCtBjjWDsbyDImn","jgDOYIsPG3c9Jk7mysodavhQxXhV"],"show_names":["Dugout Daily","The Overtime Report"]},"headline":{"total":36123160.0,"total_growth":9.720099772604962,"youtube":1691211.0,"youtube_growth":null,"audio":499050.0,"audio_growth":-73.63766889482642,"social":33773406.0,"social_growth":441.5721709893556},"has_data":true,"urls":{"network":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/yDOF1QDhp4fJsSahuI0L","public":"https://listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/yDOF1QDhp4fJsSahuI0L"}},{"object":"report","id":"U408eAHMUK0pl7OlcvFU","title":"Executive summary","network_name":"Northwind Audio","time_range":"30d","comparison_mode":"previous_period","created_at":"2026-10-14T07:54:14.099000+00:00","updated_at":null,"created_by":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_via":"app","is_automated":false,"is_test":false,"template_id":null,"element_count":0,"element_ids":[],"element_metrics":[],"element_types":{},"report_scope":{"is_single_show":false,"scope_label":"Multiple Shows","detail_text":"13 shows included","show_count":13,"show_ids":["sLLP2LKo9LJHqRCtBjjWDsbyDImn","jgDOYIsPG3c9Jk7mysodavhQxXhV"],"show_names":["Dugout Daily","The Overtime Report"]},"headline":{"total":36120722.0,"total_growth":9.74349297032353,"youtube":1691211.0,"youtube_growth":null,"audio":499050.0,"audio_growth":-73.63766889482642,"social":33770968.0,"social_growth":441.7254654737177},"has_data":true,"urls":{"network":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/U408eAHMUK0pl7OlcvFU","public":"https://listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/U408eAHMUK0pl7OlcvFU"}}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"kind":"reports","templates":[],"filters":{"search":null},"built_in_template_count":0,"custom_template_count":0,"computed_at":"2026-10-14T17:34:30.743194+00:00","cache_age_seconds":25.2,"note":null,"total":125}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:read"]}],"x-required-scope":"reports:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/reports\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/reports\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/reports\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"create_shared_report","summary":"Publish a shared report","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Publish a shared report with a frozen analytics snapshot and return its id and public URL. Needs `\"confirm\": true` because creating it publishes it: the page at `urls.public` is public and immutable (only `DELETE /v1/reports/{report_id}` changes it).\n\n`template_id` is a built-in (`network-overview`, `executive-summary`, `audio-template`, `social-reach`, `short-form`, `youtube-focused`, `cluster-overview`, `<platform>-focused` …) or a custom id from `GET /v1/report-templates`; `add_element_ids` / `remove_element_ids` adjust its elements. `time_range` is `7d`, `30d` or `90d`; on 90 days reach totals, trends and growth come from stored history while per-platform likes, comments and posts cover the last 30 days (noted in `warnings`). A dry run summarises the snapshot.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `\"confirm\": true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `reports:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Title."},"template_id":{"type":"string"},"time_range":{"default":"30d","enum":["7d","30d","90d"],"type":"string","description":"7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today."},"add_element_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"remove_element_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null},"comparison_mode":{"default":"previous_period","enum":["previous_period","none"],"type":"string","description":"previous_period or none."},"show_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Limit to these show ids (default: every show in the workspace)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false,"required":["title","template_id"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"report","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/sharedReports/p92xoYDOgoWiIvAGr0Pa","id":"p92xoYDOgoWiIvAGr0Pa","method":"add","written":{"title":"Monthly performance recap","elements":[{"id":"kpi-audio-reach","type":"kpi","category":"kpis","name":"Audio Consumption","metric":"audioReach","icon":"fas fa-headphones"},{"id":"kpi-applePodcasts-reach","type":"kpi","category":"kpis","name":"Apple Podcasts Reach","metric":"platformReach","platform":"applePodcasts","icon":"fab fa-apple"}],"data":{"totalReach":35838955,"reachGrowth":-53.529957137007656,"totalYoutubeReach":1699627,"youtubeGrowth":-36.5983046396352,"totalAudioReach":354734,"audioGrowth":-79.67041374508213,"totalSocialReach":33784594,"socialGrowth":-53.526879710025156,"reachData":[{"date":"Sep 15","value":1546342},{"date":"Sep 16","value":10593158}],"youtubeReachData":[{"date":"Sep 15","value":77798},{"date":"Sep 16","value":122746}],"audioReachData":[{"date":"Sep 15","value":60331},{"date":"Sep 16","value":117799}],"socialReachData":[{"date":"Sep 15","value":1408213},{"date":"Sep 16","value":10352613}],"showsRanking":[{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg","totalReach":26429121,"youtubeReach":0,"audioReach":95919,"socialReach":26333202,"growth":83.47935920462142},{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","image":"https://images.example.com/listener/498a319e58218172.jpg","totalReach":5006355,"youtubeReach":0,"audioReach":29011,"socialReach":4977344,"growth":-89.77629167629624}],"platformTrendData":{"youtube":[{"date":"Sep 15","value":77798},{"date":"Sep 16","value":122746}],"instagram":[{"date":"Sep 15","value":429254},{"date":"Sep 16","value":2492071}],"tiktok":[{"date":"Sep 15","value":0},{"date":"Sep 16","value":23419}],"twitter":[{"date":"Sep 15","value":978959},{"date":"Sep 16","value":7837123}],"spotify":[{"date":"Sep 15","value":60159},{"date":"Sep 16","value":117457}],"applePodcasts":[{"date":"Sep 15","value":172},{"date":"Sep 16","value":342}],"megaphone":[{"date":"Sep 15","value":0},{"date":"Sep 16","value":0}],"omnystudio":[{"date":"Sep 15","value":0},{"date":"Sep 16","value":0}]},"platformGrowth":{"youtube":-36.5983046396352,"instagram":-47.940749688505804,"tiktok":5.960717443343276,"twitter":-57.01242896991317,"spotify":-83.06823555689729,"applePodcasts":-79.36341378104233,"megaphone":-100.0,"omnystudio":183.82319845163613},"platformTotals":{"youtube":1699627,"instagram":7666139,"tiktok":2015820,"twitter":24102635,"spotify":291087,"applePodcasts":590,"megaphone":0,"omnystudio":63057},"platformBreakdown":[{"name":"X (Twitter)","value":24102635},{"name":"Instagram","value":7666139}],"avgPerformancePerPost":{"youtube":7017.75,"instagram":55551.73188405797,"tiktok":25516.708860759492,"linkedin":0.0,"twitter":163963.50340136053,"facebook":0.0,"threads":0.0,"beehiiv":0.0,"substack":0.0},"youtubeMetrics":{"lifetimeViews":55338008,"views":1699627,"watchTime":16504666,"subscribers":200610,"subscribersGained":4183,"avgViewDuration":356.2857142857143,"viewsGrowth":91.4220713034762,"watchTimeGrowth":0,"subscribersGrowth":0,"subsGainedGrowth":25.42728635682159,"avgDurationGrowth":0},"instagramMetrics":{"followers":2530286,"plays":7666139,"engagement":343546,"likes":333471,"comments":10073,"shares":2,"followersGrowth":0,"playsGrowth":914.4635853081446,"engagementGrowth":1303.546186215631},"tiktokMetrics":{"followers":183213,"plays":2015820,"engagement":157978,"likes":136295,"comments":4371,"shares":17312,"followersGrowth":0,"playsGrowth":443.08275477462485,"engagementGrowth":763.6925263790936},"facebookMetrics":{"followers":7800,"views":0,"engagement":0,"likes":0,"comments":0,"shares":0,"followersGrowth":0,"viewsGrowth":0,"engagementGrowth":0},"twitterMetrics":{"followers":1579885,"impressions":24102635,"engagement":174756,"likes":152894,"retweets":14811,"replies":4576,"quotes":2475,"followersGrowth":0,"impressionsGrowth":1602.857379030862,"engagementGrowth":434.4056756674108},"spotifyMetrics":{"streams":291087,"totalStreams":80910297,"followers":323863,"episodes":15486,"avgStreams":7702,"consumptionHours":81505.23,"totalConsumptionHours":18712443.50999994,"rating":4.7,"topCountry":"United States","streamsGrowth":-83.06823555689729,"followersGrowth":0,"avgStreamsGrowth":-25.490954822482344,"consumptionHoursGrowth":-84.77568542704255},"applePodcastsMetrics":{"plays":679,"totalPlays":419206767,"followers":355508,"listeners":232,"totalListeners":1605511,"engagedListeners":1165291,"hoursListened":37783544,"totalHoursListened":37783544,"avgPlays":283,"episodes":1,"topCountry":"United States","playsGrowth":-76.30844382414514,"followersGrowth":0,"listenersGrowth":-74.7276688453159,"engagedListenersGrowth":0,"hoursListenedGrowth":0,"avgPlaysGrowth":-57.315233785822016},"threadsMetrics":{"reach":0,"reachGrowth":0,"daysWithData":1,"engagement":2,"engagementGrowth":100,"followers":9350},"megaphoneMetrics":{"downloads":0,"downloadsGrowth":0,"daysWithData":0,"overviewDownloads":0,"overviewStreams":0,"overviewPlays":0,"externalAnalyticsLoaded":false},"omnystudioMetrics":{"downloads":63057,"lifetimeDownloads":2846561,"estimatedReach":0,"hoursListened":78347,"episodes":872,"avgDownloads":4504,"downloadsGrowth":250.55036691127418,"avgDownloadsGrowth":250.5058365758755,"lifetimeDownloadsGrowth":0,"estimatedReachGrowth":0,"hoursListenedGrowth":0,"episodesGrowth":0},"clusterMetrics":{"clusterCount":12,"totalReach":87263,"youtubeReach":68228,"youtubeLongFormReach":64066,"youtubeShortsReach":4162,"audioReach":4477,"socialReach":14558,"longFormReach":68543,"shortFormReach":18720,"longFormCount":11,"shortFormCount":16,"clips":27,"posts":0,"totalEngagement":1432,"engagementRate":1.6410162382682236,"avgReachPerCluster":7271.916666666667,"avgYoutubeReachPerCluster":5685.666666666667,"avgYoutubeLongFormReachPerCluster":5338.833333333333,"avgYoutubeShortsReachPerCluster":346.8333333333333,"avgAudioReachPerCluster":373.0833333333333,"avgSocialReachPerCluster":1213.1666666666667,"avgLongFormReachPerCluster":5711.916666666667,"avgShortFormReachPerCluster":1560.0,"avgLongFormCountPerCluster":0.9166666666666666,"avgShortFormCountPerCluster":1.3333333333333333,"avgClipsPerCluster":2.25,"avgPostsPerCluster":0.0,"avgEngagementPerCluster":119.33333333333333,"countGrowth":-33.33333333333333,"reachGrowth":-96.36663346812607,"youtubeGrowth":-65.88787616681083,"youtubeLongFormGrowth":-65.49748229528502,"youtubeShortsGrowth":-70.94792684629346,"audioGrowth":-72.67289263260696,"socialGrowth":-99.33382693045131,"longFormGrowth":-66.07924065166182,"shortFormGrowth":-99.14895319424416,"avgReachGrowth":-94.54995020218911,"avgYoutubeGrowth":-48.83181425021624,"avgAudioGrowth":-59.009338948910454,"avgSocialGrowth":-99.00074039567697,"avgLongFormGrowth":-49.11886097749272,"avgShortFormGrowth":-98.72342979136623,"hasReachDistributionData":true,"hasContentMixData":true,"clusterDocCount":159,"sourceClusterCount":144,"mergedClusterCount":15,"manualClusterCount":11,"emptyClusterCount":22,"unlinkedClusterCount":0,"undatedClusterCount":1,"episodeCount":134,"contentPieces":27,"reachDistributionData":[{"name":"Mailbag: your questions answered","value":68228,"color":"#FF0000"},{"name":"What the numbers really say","value":4477,"color":"#8B5CF6"}],"contentMixData":[{"name":"The rookie who changed everything","value":68543,"color":"#2563EB"},{"name":"Inside the locker room with a two-time champion","value":18720,"color":"#F59E0B"}]},"window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"},"metricWindows":{"reach":"30d","platformMetrics":"30d"},"coverage":{"start":"2019-11-26","embedded_boundary":"2026-09-15","history_used":true,"days_with_data":29,"previous_days_with_data":30,"previous_window_coverage_days":30,"previous_window_days":30,"growth_basis":"total","growth_platforms":null,"previous_platform_coverage":{},"warnings":[]},"generatedBy":"mcp"},"networkName":"Northwind Audio","timeRange":"30d","comparisonMode":"previous_period","reportScope":{"isSingleShow":false,"scopeLabel":"Multiple Shows","detailText":"12 shows included","showCount":12,"logos":[{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg"},{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","image":"https://images.example.com/listener/498a319e58218172.jpg"}]},"createdAt":"2026-10-14T17:34:30.815Z","createdBy":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","createdVia":"mcp","templateId":"audio-template"},"warnings":["Shared reports cannot be edited after creation; delete and recreate to change them."],"urls":{"app":"https://network.listener.com/app/reports?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/p92xoYDOgoWiIvAGr0Pa"},"error":null,"data":{"report_id":"p92xoYDOgoWiIvAGr0Pa","template_name":"Audio Template","element_ids":["kpi-audio-reach","kpi-applePodcasts-reach"],"report_scope":{"isSingleShow":false,"scopeLabel":"Multiple Shows","detailText":"12 shows included","showCount":12,"logos":[{"id":"sLLP2LKo9LJHqRCtBjjWDsbyDImn","name":"Dugout Daily","image":"https://images.example.com/listener/09c3beb030eae9d0.jpg"},{"id":"jgDOYIsPG3c9Jk7mysodavhQxXhV","name":"The Overtime Report","image":"https://images.example.com/listener/498a319e58218172.jpg"}]},"confirm_required":true,"snapshot_summary":{"total_reach":35838955,"reach_growth":-53.529957137007656,"shows":12,"cluster_count":12,"window":{"time_range":"30d","kind":"rolling","start":"2026-09-15","end":"2026-10-14","days":30,"previous_start":"2026-08-16","previous_end":"2026-09-14"}},"snapshot_gaps":{"kpi-*-followers (social)":"follower deltas come from live socialStats; growth is reported as 0","table-shows-ranking.image":"show images are the profile logo, not the analytics page's resolved artwork"}},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:write"]}],"x-required-scope":"reports:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/reports\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"title\": \"TITLE\", \"template_id\": \"TEMPLATE_ID\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/reports\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"title\": \"TITLE\", \"template_id\": \"TEMPLATE_ID\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/reports\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'title': 'TITLE', 'template_id': 'TEMPLATE_ID', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/reports/{report_id}":{"get":{"operationId":"get_report","summary":"Retrieve a report","tags":["Reports"],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string"},"description":"Shared report id (see GET /v1/reports)."},{"name":"include_data","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One shared report: metadata, scope, headline numbers, every element (KPIs, charts, tables, text) and, with `include_data=true`, the stored snapshot the public page renders. The snapshot is what was computed when the report was published; arrays over 200 items are truncated (`data_truncated`).\n\n- Required scope: `reports:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetReportResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"report"}}}]},"example":{"object":"report","id":"yDOF1QDhp4fJsSahuI0L","title":"Executive summary","network_name":"Northwind Audio","time_range":"30d","comparison_mode":"previous_period","created_at":"2026-10-14T07:57:01.185000+00:00","updated_at":null,"created_by":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","created_via":"app","is_automated":false,"is_test":false,"template_id":null,"element_count":10,"element_ids":["kpi-cluster-count","kpi-cluster-total-reach"],"element_metrics":["clusterCount","clusterLongFormReach"],"element_types":{"chart":1,"episode":2,"kpi":4,"table":3},"report_scope":{"is_single_show":false,"scope_label":"Multiple Shows","detail_text":"13 shows included","show_count":13,"show_ids":["sLLP2LKo9LJHqRCtBjjWDsbyDImn","jgDOYIsPG3c9Jk7mysodavhQxXhV"],"show_names":["Dugout Daily","The Overtime Report"]},"headline":{"total":36123160.0,"total_growth":9.720099772604962,"youtube":1691211.0,"youtube_growth":null,"audio":499050.0,"audio_growth":-73.63766889482642,"social":33773406.0,"social_growth":441.5721709893556},"has_data":true,"urls":{"network":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/yDOF1QDhp4fJsSahuI0L","public":"https://listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/yDOF1QDhp4fJsSahuI0L"},"elements":[{"id":"kpi-cluster-count","instance_id":null,"type":"kpi","category":"kpis","name":"Cluster Count","metric":"clusterCount","platform":null,"chart_type":null,"text_type":null,"content":null,"max_rows":null,"has_episode_data":false},{"id":"kpi-cluster-total-reach","instance_id":null,"type":"kpi","category":"kpis","name":"Total Cluster Reach","metric":"clusterTotalReach","platform":null,"chart_type":null,"text_type":null,"content":null,"max_rows":null,"has_episode_data":false}],"data":null,"data_keys":["applePodcastsMetrics","rmm89Hrhvccj"],"data_truncated":false,"computed_at":"2026-10-14T17:34:30.819895+00:00","cache_age_seconds":25.3,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:read"]}],"x-required-scope":"reports:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/reports/REPORT_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/reports/REPORT_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/reports/REPORT_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"delete":{"operationId":"delete_shared_report","summary":"Delete a shared report","tags":["Reports"],"parameters":[{"name":"report_id","in":"path","required":true,"schema":{"type":"string"},"description":"Shared report id (see GET /v1/reports)."},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"name":"confirm","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Permanently delete a shared report so its public page stops resolving, and list report automations whose last report still points at it (left as is, listed in `warnings`).\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `?confirm=true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `reports:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"report","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/sharedReports/yDOF1QDhp4fJsSahuI0L","id":"yDOF1QDhp4fJsSahuI0L","method":"delete","written":{"deleted":true,"report":{"id":"yDOF1QDhp4fJsSahuI0L","createdAt":"2026-10-14T07:57:01.185Z","timeRange":"30d","title":"Executive summary"},"automation_ids":[],"public_url":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/yDOF1QDhp4fJsSahuI0L"},"warnings":[],"urls":{"app":"https://network.listener.com/app/reports?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":null},"error":null,"data":{"report_id":"yDOF1QDhp4fJsSahuI0L","automation_ids":[],"confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:write"]}],"x-required-scope":"reports:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/reports/REPORT_ID?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/reports/REPORT_ID?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/reports/REPORT_ID?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/report-templates":{"get":{"operationId":"list_report_templates","summary":"List report templates","tags":["Reports"],"parameters":[{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Case-insensitive text filter."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Report templates: the built-in ones plus the workspace's custom templates, with their element ids. Use a template's `id` as `template_id` in `POST /v1/reports`.\n\n- Required scope: `reports:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ReportTemplateRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"report_template"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"kind":{"enum":["reports","templates"],"title":"Kind","type":"string"},"reports":{"items":{"$ref":"#/components/schemas/ReportRow"},"title":"Reports","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"built_in_template_count":{"default":0,"title":"Built In Template Count","type":"integer"},"custom_template_count":{"default":0,"title":"Custom Template Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/report-templates","data":[{"object":"report_template","id":"audio-template","name":"Audio Template","description":"Focus on audio content metrics and trends","icon":"fas fa-headphones","built_in":true,"automation":true,"dynamic":false,"element_count":6,"element_ids":["kpi-audio-reach","kpi-applePodcasts-reach"],"elements":[],"created_at":null,"updated_at":null},{"object":"report_template","id":"social-reach","name":"Social Reach","description":"Comprehensive social media performance","icon":"fas fa-share-alt","built_in":true,"automation":true,"dynamic":false,"element_count":8,"element_ids":["kpi-social-reach","kpi-instagram-reach"],"elements":[],"created_at":null,"updated_at":null}],"has_more":true,"next_cursor":"eyJvIjoyfQ","meta":{"kind":"templates","reports":[],"filters":{"search":null},"built_in_template_count":13,"custom_template_count":0,"computed_at":"2026-10-14T17:34:31.342564+00:00","cache_age_seconds":25.8,"note":null,"total":13}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:read"]}],"x-required-scope":"reports:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/report-templates\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/report-templates\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/report-templates\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"create_report_template","summary":"Save a report template","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Save a custom report template from a list of element ids (see `GET /v1/report-templates` for the elements the built-ins use). Nothing is published; use the returned id as `template_id` in `POST /v1/reports`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `reports:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name."},"element_ids":{"items":{"type":"string"},"type":"array"},"description":{"default":"","type":"string","description":"Free-text description."},"comparison_mode":{"default":"previous_period","enum":["previous_period","none"],"type":"string","description":"previous_period or none."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["name","element_ids"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"report_template","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/XXfzcGxkLsQaKAvRy1SwLsZCcH78/reportsTemplates/YNYJCcbZLfiZ3hU9z9FI","id":"YNYJCcbZLfiZ3hU9z9FI","method":"add","written":{"name":"API probe (dry run)","description":"","icon":"fas fa-user-edit","elements":[{"id":"kpi-audio-reach","type":"kpi","category":"kpis","name":"Audio Consumption","metric":"audioReach","icon":"fas fa-headphones"},{"id":"kpi-applePodcasts-reach","type":"kpi","category":"kpis","name":"Apple Podcasts Reach","metric":"platformReach","platform":"applePodcasts","icon":"fab fa-apple"}],"createdAt":"2026-10-14T17:34:31.345Z","elementIds":["kpi-audio-reach","kpi-applePodcasts-reach"],"comparisonMode":"previous_period"},"warnings":[],"urls":{"app":"https://network.listener.com/app/reports?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":null},"error":null,"data":{"element_ids":["kpi-audio-reach","kpi-applePodcasts-reach"]},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:write"]}],"x-required-scope":"reports:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/report-templates\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"NAME\", \"element_ids\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/report-templates\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"name\": \"NAME\", \"element_ids\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/report-templates\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'name': 'NAME', 'element_ids': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/report-automations":{"get":{"operationId":"list_report_automations","summary":"List report automations","tags":["Reports"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Scheduled report automations: template, frequency, time range, shows, delivery (email masked, Slack configured or not, never the webhook), enabled flag, last and next run, last report URLs and delivery guardrails.\n\n- Required scope: `reports:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ReportAutomationRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"report_automation"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"total":{"title":"Total","type":"integer"},"enabled_count":{"default":0,"title":"Enabled Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/report-automations","data":[{"object":"report_automation","id":"H0tWUl7HNJQSkYF3QF5W","owner_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","title":"Executive summary","template_id":"cluster-overview","template_name":"Cluster Overview","template_is_built_in":true,"element_ids":["kpi-cluster-total-reach","kpi-cluster-youtube-reach"],"frequency":"weekly","time_range":"30d","time_range_label":"Last 30 days","comparison_mode":"previous_period","selected_show_ids":["paAtKPJGo56md5VyoEQ9Las7qahL","0Hq6ZhayEg3a3GGHVwdzCtAkiV9H"],"selected_show_names":["Hard Court","The Bullpen"],"delivery_method":"slack","recipient_email_masked":null,"slack_configured":true,"enabled":true,"start_date":null,"created_at":"2026-04-24T14:01:10.490000+00:00","last_run":"2026-10-10T08:00:21.920000+00:00","next_run":"2026-10-16T18:05:12.879000+00:00","last_report_id":"JiQNJsUwY0LlE4vESOXZ","last_report_urls":{"network":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/JiQNJsUwY0LlE4vESOXZ","public":"https://listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/JiQNJsUwY0LlE4vESOXZ"},"last_error":null,"last_error_at":null,"last_delivery_blocked":false,"last_delivery_block_reasons":[],"last_delivery_zero_kpi_count":0},{"object":"report_automation","id":"y4AGCrBcehPQVzcmsLa7","owner_uid":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","title":"Weekly network report","template_id":"network-overview","template_name":"Network Overview","template_is_built_in":true,"element_ids":["kpi-network-reach","kpi-youtube-reach"],"frequency":"weekly","time_range":"7d","time_range_label":"Last 7 days","comparison_mode":"previous_period","selected_show_ids":[],"selected_show_names":[],"delivery_method":"email","recipient_email_masked":"c***@mxsxmlhkfvuhc15","slack_configured":null,"enabled":true,"start_date":null,"created_at":"2026-02-06T18:14:09.184000+00:00","last_run":"2026-10-12T08:00:56.100000+00:00","next_run":"2026-10-19T08:00:19.803000+00:00","last_report_id":"RdLMz1J8JQ55WD2zhDee","last_report_urls":{"network":"https://network.listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/RdLMz1J8JQ55WD2zhDee","public":"https://listener.com/report/XXfzcGxkLsQaKAvRy1SwLsZCcH78/RdLMz1J8JQ55WD2zhDee"},"last_error":null,"last_error_at":null,"last_delivery_blocked":false,"last_delivery_block_reasons":[],"last_delivery_zero_kpi_count":0}],"has_more":false,"next_cursor":null,"meta":{"total":3,"enabled_count":3,"computed_at":"2026-10-14T17:34:31.347284+00:00","cache_age_seconds":25.8,"note":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:read"]}],"x-required-scope":"reports:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/report-automations\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/report-automations\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/report-automations\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/report-automations/{automation_id}/disable":{"post":{"operationId":"disable_report_automation","summary":"Disable a report automation","tags":["Reports"],"parameters":[{"name":"automation_id","in":"path","required":true,"schema":{"type":"string"},"description":"Report automation id (see GET /v1/report-automations)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Disable a scheduled report automation so it stops emailing or posting reports. Creating, enabling and deleting automations send outbound email and are app-only.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `reports:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"report_automation","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"reportAutomations/H0tWUl7HNJQSkYF3QF5W","id":"H0tWUl7HNJQSkYF3QF5W","method":"update","written":{"enabled":false},"warnings":[],"urls":{"app":"https://network.listener.com/app/reports?uid=XXfzcGxkLsQaKAvRy1SwLsZCcH78","public":null},"error":null,"data":{"automation_id":"H0tWUl7HNJQSkYF3QF5W","title":"Executive summary"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["reports:write"]}],"x-required-scope":"reports:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/report-automations/AUTOMATION_ID/disable\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/report-automations/AUTOMATION_ID/disable\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/report-automations/AUTOMATION_ID/disable\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/sponsors/matches":{"get":{"operationId":"match_sponsors","summary":"Match sponsors","tags":["Sponsors"],"parameters":[{"name":"show_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"episode_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Episode id (see GET /v1/shows/{show_id}/episodes)."},{"name":"brief","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"limit","in":"query","required":false,"schema":{"default":5,"maximum":10,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Rank the brands this workspace already knows (campaign brands, invites, network sponsors, cluster sponsor tags, show collaborations) by fit for a show, an episode or a free-text `brief`, with the reason and proof points for each. Send at least one of `show_id`, `episode_id` (with `show_id`) or `brief`. Contact emails are never returned.\n\n- Required scope: `sponsors:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SponsorMatch"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"sponsor_match"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"inventory_size":{"title":"Inventory Size","type":"integer"},"inventory_sources":{"additionalProperties":{"type":"integer"},"description":"Candidates per primary source.","title":"Inventory Sources","type":"object"},"context":{"additionalProperties":true,"description":"What was matched against: show, episode, brief.","title":"Context","type":"object"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Id"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/sponsors/matches","data":[{"object":"sponsor_match","sponsor_id":"brand-globex-sports","name":"Globex Sports","slug":"globex-sports","domain":"globex-sports.example.com","logo":"https://www.example.com/cd0528ea","source":"campaign_brand","sources":["campaign_brand","brand_invite"],"fit_score":34,"matched_terms":["northwind"],"reason":"New episode out now. We break down the week's biggest storylines and answer your questions.","proof_points":["Ran campaign \"Globex Sports Campaign\" (active).","Ran campaign \"Auto\" (active)."],"campaign_count":2,"invite_status":"accepted","industry":null,"brand_public_url":"https://network.listener.com/northwind-audio/brands/globex-sports"},{"object":"sponsor_match","sponsor_id":"brand-acmecoffee","name":"Umbrella Energy","slug":"acmecoffee","domain":"acme-coffee.example.com","logo":"https://images.example.com/listener/a3504ff4873daa28.png","source":"campaign_brand","sources":["campaign_brand","brand_invite"],"fit_score":32,"matched_terms":["northwind"],"reason":"A deep dive into the numbers behind the season so far.","proof_points":["Ran campaign \"Hard Court × Umbrella Energy Test\" (active).","Brand account accepted the invitation."],"campaign_count":1,"invite_status":"accepted","industry":null,"brand_public_url":"https://network.listener.com/northwind-audio/brands/acmecoffee"}],"has_more":false,"next_cursor":null,"meta":{"inventory_size":9,"inventory_sources":{"campaign_brand":8,"collaboration":1},"context":{"show":"The Long Game","show_categories":["Sports","Basketball"],"episode_title":null,"brief":null},"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","episode_id":null,"computed_at":"2026-10-14T17:34:31.504251+00:00","cache_age_seconds":26.0,"note":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["sponsors:read"]}],"x-required-scope":"sponsors:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/sponsors/matches\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/sponsors/matches\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/sponsors/matches\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/sponsors/opportunities":{"get":{"operationId":"get_network_opportunities","summary":"Network bundle opportunities","tags":["Sponsors"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":6,"maximum":30,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"name":"include_reach","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"name":"include_empty_shows","in":"query","required":false,"schema":{"default":false,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Pairs of the workspace's shows worth bundling for a sponsor: shared categories, collaboration history, shared hosts and, with `include_reach=true`, their combined cluster reach and a score. Reach is skipped automatically on very large networks (`meta.reach_aware=false`).\n\n- Required scope: `sponsors:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/NetworkOpportunity"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"sponsor_opportunity"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"total_pairs_considered":{"title":"Total Pairs Considered","type":"integer"},"reach_aware":{"description":"True when combined_reach / score used cluster reach.","title":"Reach Aware","type":"boolean"},"reach_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'cluster_summaries' when reach was loaded.","title":"Reach Source"},"show_count":{"title":"Show Count","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/sponsors/opportunities","data":[{"object":"sponsor_opportunity","pair":"The Bullpen x Box Score Breakdown","show_ids":["0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","Of9Els0RskCtlyZFPG8ujblH3NKI"],"show_names":["The Bullpen","Box Score Breakdown"],"reason":"Highlights and analysis from the latest matchday.","overlap_categories":["Sports News","News"],"combined_collaborations":0,"combined_reach":622011.0,"shared_hosts":[],"score":63.18},{"object":"sponsor_opportunity","pair":"The Bullpen x The Long Game","show_ids":["0Hq6ZhayEg3a3GGHVwdzCtAkiV9H","i3KlnFag2DgIpykraVxjrIZwJYcL"],"show_names":["The Bullpen","The Long Game"],"reason":"The crew is back with rankings, hot takes and a listener mailbag.","overlap_categories":["Sports News","News"],"combined_collaborations":0,"combined_reach":623242.0,"shared_hosts":[],"score":53.18}],"has_more":false,"next_cursor":null,"meta":{"total_pairs_considered":66,"reach_aware":true,"reach_source":"cluster_summaries","show_count":12,"missing_show_ids":["0Iush8rT5eCcD4ePHroKFDlQvKhT","nCJuUMzGC6EE3dfruqjRHtYdlCTr"],"computed_at":"2026-10-14T17:34:31.508349+00:00","cache_age_seconds":26.0,"note":null}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["sponsors:read"]}],"x-required-scope":"sponsors:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/sponsors/opportunities\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/sponsors/opportunities\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/sponsors/opportunities\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/sponsorship-packages":{"get":{"operationId":"list_sponsorship_packages","summary":"List sponsorship packages","tags":["Sponsors"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"window","in":"query","required":false,"schema":{"anyOf":[{"enum":[30,90,365],"type":"integer"},{"type":"null"}],"default":null},"description":"Reporting window."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"A show's sponsorship packages (rate card) with each deliverable's projected reach from recent content: average listens per audio read, views per video integration or social clip, opens per newsletter placement. `window` (30, 90 or 365 days) overrides each package's trailing window; averages built from measured content are marked verified.\n\n- Required scope: `sponsors:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SponsorshipPackage"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"sponsorship_package"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"window":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Override applied to every package (30 | 90 | 365); None keeps each package's own trailing window.","title":"Window"},"stats_by_window":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/WindowStat"},"type":"object"},"description":"Trailing window ('30' | '90' | '365') → average reach per format (audio, video, short_form, newsletter).","title":"Stats By Window","type":"object"},"clusters_considered":{"default":0,"title":"Clusters Considered","type":"integer"},"clusters_available":{"default":0,"title":"Clusters Available","type":"integer"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/shows/i3KlnFag2DgIpykraVxjrIZwJYcL/sponsorship-packages","data":[],"has_more":false,"next_cursor":null,"meta":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","show_name":"The Long Game","window":null,"stats_by_window":{"90":{"audio":{"average":0.0,"count":0,"open_rate":null},"video":{"average":0.0,"count":0,"open_rate":null},"short_form":{"average":0.0,"count":0,"open_rate":null},"newsletter":{"average":0.0,"count":0,"open_rate":0.0}}},"clusters_considered":1,"clusters_available":1,"public_url":"https://listener.com/the-long-game","computed_at":"2026-10-14T17:34:31.511843+00:00","cache_age_seconds":26.0,"note":"This show has no sponsorship packages yet; add them in the show's profile."}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["sponsors:read"]}],"x-required-scope":"sponsors:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/sponsorship-packages\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/sponsorship-packages\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/sponsorship-packages\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/library/files":{"get":{"operationId":"list_workspace_library_files","summary":"List library files","tags":["Library & research"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Files in the workspace library, newest upload first: filename, type, size, parse status, whether extracted text is available and a short preview.\n\n- Required scope: `library:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/LibraryFile"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"library_file"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"storage_configured":{"description":"True when a Storage bucket is configured, so `GET /v1/library/files/{file_id}` can sign download URLs.","title":"Storage Configured","type":"boolean"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/library/files","data":[{"object":"library_file","id":"eXfXrq21X1w6eEqepyvu","filename":"document-1bd0fd.csv","media_type":"text/csv","size_bytes":35314,"detected_kind":"csv","is_text_like":true,"parse_status":"parsed","parse_warnings":[],"status":"ready","uploaded_at":"2026-04-28T11:33:04.257000+00:00","uploaded_by_uid":null,"has_extracted_text":true,"extracted_text_chars":7469,"has_structured_summary":true,"preview":"The crew is back with rankings, hot takes and a listener mailbag."},{"object":"library_file","id":"FpSVuQd6d0tFQjmSnKtE","filename":"document-3e829c.pdf","media_type":"application/pdf","size_bytes":4491186,"detected_kind":"pdf","is_text_like":false,"parse_status":"parsed","parse_warnings":["Extracted text was truncated to 12000 characters."],"status":"ready","uploaded_at":"2026-04-28T10:42:36.206000+00:00","uploaded_by_uid":null,"has_extracted_text":true,"extracted_text_chars":12001,"has_structured_summary":false,"preview":"Clip from this week's episode. Full episode on YouTube and Spotify."}],"has_more":false,"next_cursor":null,"meta":{"storage_configured":true,"computed_at":"2026-10-14T17:34:31.513771+00:00","cache_age_seconds":26.0,"note":null,"total":2}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["library:read"]}],"x-required-scope":"library:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/library/files\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/library/files\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/library/files\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/library/files/{file_id}":{"get":{"operationId":"get_workspace_library_file","summary":"Retrieve a library file","tags":["Library & research"],"parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string"},"description":"Library file id (see GET /v1/library/files)."},{"name":"include_text","in":"query","required":false,"schema":{"default":true,"type":"boolean"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"One library file: metadata, extracted text (up to 12,000 characters), the structured summary when one exists and a 1-hour signed download URL. `include_text=false` returns metadata and the link only.\n\n- Required scope: `library:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GetWorkspaceLibraryFileResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"library_file"}}}]},"example":{"object":"library_file","id":"eXfXrq21X1w6eEqepyvu","filename":"document-1bd0fd.csv","media_type":"text/csv","size_bytes":35314,"detected_kind":"csv","is_text_like":true,"parse_status":"parsed","parse_warnings":[],"status":"ready","uploaded_at":"2026-04-28T11:33:04.257000+00:00","uploaded_by_uid":null,"has_extracted_text":true,"extracted_text_chars":7469,"has_structured_summary":true,"preview":"The crew is back with rankings, hot takes and a listener mailbag.","extracted_text":"The crew is back with rankings, hot takes and a listener mailbag.","extracted_text_truncated":false,"structured_summary":"The crew is back with rankings, hot takes and a listener mailbag.","storage_path":"workspace-library/XXfzcGxkLsQaKAvRy1SwLsZCcH78/eXfXrq21X1w6eEqepyvu/contacts-export.csv","download_url":"https://images.example.com/listener/637cd7ad932cd90e.jpg","download_url_expires_at":"2026-10-14T18:34:31.527234+00:00","computed_at":"2026-10-14T17:34:31.516322+00:00","cache_age_seconds":26.0,"note":null}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["library:read"]}],"x-required-scope":"library:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/library/files/FILE_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/library/files/FILE_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/library/files/FILE_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/research/web":{"get":{"operationId":"web_research","summary":"Web research","tags":["Library & research"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Search text."},{"name":"max_results","in":"query","required":false,"schema":{"default":5,"maximum":10,"minimum":1,"type":"integer"}},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Search the public web and return titles, URLs and snippets plus a short summary of the top hits, for context outside Listener (a brand's news, a competitor's show). `configured=false` with a note when search is not set up on this server, never an error.\n\n- Required scope: `library:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/WebResearchResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"web_research"}}}]},"example":{"object":"web_research","query":"podcast advertising trends","configured":false,"summary":null,"sources":[],"total_results":null,"computed_at":"2026-10-14T17:34:31.530801+00:00","cache_age_seconds":26.0,"note":"Web research is not configured. Set GOOGLE_SEARCH_API_KEY and GOOGLE_SEARCH_ENGINE_ID to enable Google Custom Search lookups."}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["library:read"]}],"x-required-scope":"library:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/research/web?query=QUERY\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/research/web?query=QUERY\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/research/web?query=QUERY\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/podcasts/search":{"get":{"operationId":"search_podcasts","summary":"Search podcasts","tags":["Library & research"],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Search text."},{"name":"limit","in":"query","required":false,"schema":{"default":10,"maximum":20,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Search podcasts outside the workspace (prospects, competitors, a guest's own show) by name or keyword: title, publisher, artwork, categories, episode count, Apple / Spotify ids and RSS URL. `configured=false` with a note when the search provider is not configured.\n\n- Required scope: `library:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PodcastSearchResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"podcast"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"query":{"title":"Query","type":"string"},"configured":{"title":"Configured","type":"boolean"},"total":{"default":0,"title":"Total","type":"integer"},"source":{"default":"podchaser","title":"Source","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/podcasts/search","data":[],"has_more":false,"next_cursor":null,"meta":{"query":"basketball","configured":false,"total":0,"source":"podchaser","computed_at":"2026-10-14T17:34:31.532657+00:00","cache_age_seconds":26.0,"note":"Podcast search is not configured on this server: set LISTENER_INTERNAL_API_KEY (and LISTENER_APP_BASE_URL) so it can call the Listener app's Podchaser search."}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["library:read"]}],"x-required-scope":"library:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/podcasts/search?query=QUERY\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/podcasts/search?query=QUERY\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/podcasts/search?query=QUERY\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/insertion-orders/parse":{"post":{"operationId":"parse_insertion_order","summary":"Parse an insertion order","tags":["Library & research"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Read a PDF insertion order and return the extracted order, line items matched to workspace shows, rows that could not be matched, and ready-to-use `proposed_create_campaign_args` for `POST /v1/campaigns`. Writes nothing. Send exactly one source: `library_file_id` (from `GET /v1/library/files`), `file_url` (https, up to 4 MB) or `file_base64` (`upload_id` refers to a file attached in Listener's agent chat). `show_ids` narrows show matching. Review `unresolved_line_items` before creating the campaign; never guess a show or impressions.\n\n- Required scope: `library:read`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"upload_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"library_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"file_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"file_base64":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"file_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"show_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Limit to these show ids (default: every show in the workspace)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ParseInsertionOrderResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"insertion_order"}}}]},"example":{"object":"insertion_order","ok":false,"configured":false,"source":null,"io":null,"plan":null,"proposed_create_campaign_args":null,"unresolved_line_items":[],"warnings":[],"model":null,"computed_at":"2026-10-14T17:34:31.533725+00:00","cache_age_seconds":26.0,"note":"Insertion-order parsing is not configured on this server: set LISTENER_INTERNAL_API_KEY (the same value as the Listener app's) and LISTENER_APP_BASE_URL so it can call the app's extractor."}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["library:read"]}],"x-required-scope":"library:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/insertion-orders/parse\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/insertion-orders/parse\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/insertion-orders/parse\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/platforms/{platform}/refresh":{"post":{"operationId":"refresh_show_platform","summary":"Refresh a show's platform data","tags":["Refresh"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"platform","in":"path","required":true,"schema":{"enum":["youtube","instagram","instagramBusiness","tiktok","twitter","facebook","threads","linkedin","beehiiv","substack","simplecast","transistor","art19","captivate","omnystudio","spotify","applePodcasts"],"type":"string"},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"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`).\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `\"confirm\": true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `refresh:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"platform_refresh","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/i3KlnFag2DgIpykraVxjrIZwJYcL","id":"i3KlnFag2DgIpykraVxjrIZwJYcL","method":"http","written":{"userId":"i3KlnFag2DgIpykraVxjrIZwJYcL","platforms":["youtube"],"forceUpdate":true},"warnings":[],"urls":{"app":"https://network.listener.com/app/connect?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","public":null},"error":null,"data":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","platform":"youtube","kind":"server","provider_calls_estimate":"7–9 API calls","last_updated_before":"2026-10-13T09:34:22.044Z","status":"would-refresh"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["refresh:write"]}],"x-required-scope":"refresh:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/platforms/PLATFORM/refresh\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/platforms/PLATFORM/refresh\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/platforms/PLATFORM/refresh\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/data-requests":{"post":{"operationId":"request_platform_data","summary":"File a Spotify / Apple data request","tags":["Refresh"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"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`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `\"confirm\": true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `refresh:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"show_id":{"type":"string","description":"A show id in this workspace (see GET /v1/shows)."},"platform":{"enum":["spotify","applePodcasts"],"type":"string","description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},"show_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false,"required":["show_id","platform"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"data_request","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"admin_data_requests/JZw6iiMOmEUEYN3Mg4JC","id":"JZw6iiMOmEUEYN3Mg4JC","method":"add","written":{"userId":"i3KlnFag2DgIpykraVxjrIZwJYcL","userEmail":"No email available","platform":"spotify","showUrl":"https://open.spotify.com/show/2pGhC7Mvqu6L2VzmndqWLq","requestedAt":"2026-10-14T17:34:32.408Z","status":"pending","createdBy":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","createdVia":"mcp","spotifyShowUrl":"https://open.spotify.com/show/2pGhC7Mvqu6L2VzmndqWLq"},"warnings":["Status transitions are owned by the ops Slack pipeline; poll `GET /v1/integrations/status`."],"urls":{"app":"https://network.listener.com/app/connect?uid=i3KlnFag2DgIpykraVxjrIZwJYcL","public":null},"error":null,"data":{"show_id":"i3KlnFag2DgIpykraVxjrIZwJYcL","platform":"spotify","confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["refresh:write"]}],"x-required-scope":"refresh:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/data-requests\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"show_id\": \"SHOW_ID\", \"platform\": \"spotify\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/data-requests\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"show_id\": \"SHOW_ID\", \"platform\": \"spotify\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/data-requests\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'show_id': 'SHOW_ID', 'platform': 'spotify', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/account-discovery":{"get":{"operationId":"get_account_discovery","summary":"Retrieve a show's account discovery","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The social accounts Listener's discovery found for a show (YouTube, Instagram, TikTok, X, Facebook, Threads, LinkedIn): handle, profile URL, followers, confidence (`high`, `medium`, `low`) and why it was picked. Each candidate carries its connection state against the show's current integrations (`connected`, `connected_account`, `matches_candidate`) and `connect_via`: `api` (connect it with `PUT /v1/shows/{show_id}/integrations/{platform}`) or `app_sign_in` (a person signs in from `verify_url`).\n\n`verify_url` is the show's integrations page in the right Listener app (Listener Networks for network workspaces, Listener for creators); send people there to review and confirm. `status` is `none` until a run starts, then `running` or `done`.\n\n- Required scope: `shows:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AccountDiscoveryResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"account_discovery"}}}]},"example":{"object":"account_discovery","show_id":"pQ7sHt2Lw9XcV4bN1mRa","show_name":"Dugout Daily","status":"done","website":"https://dugoutdaily.example","ran_at":"2026-10-14T09:12:40.512Z","runs":1,"committed_at":null,"candidates":[{"platform":"youtube","label":"YouTube","status":"found","handle":"DugoutDaily","url":"https://www.youtube.com/@DugoutDaily","display_name":"Dugout Daily","followers":18400,"verified":false,"confidence":"high","reason":"Linked from your other accounts","connected":false,"connection_state":"disconnected","connected_account":null,"matches_candidate":null,"connect_via":"app_sign_in"},{"platform":"instagram","label":"Instagram","status":"found","handle":"dugoutdaily","url":"https://www.instagram.com/dugoutdaily/","display_name":"Dugout Daily","followers":6120,"verified":false,"confidence":"high","reason":"Listed on your website","connected":true,"connection_state":"connected","connected_account":"dugoutdaily","matches_candidate":true,"connect_via":"api"},{"platform":"tiktok","label":"TikTok","status":"found","handle":"dugout.daily","url":"https://www.tiktok.com/@dugout.daily","display_name":"Dugout Daily Clips","followers":2350,"verified":false,"confidence":"medium","reason":"Same name and avatar as the show","connected":true,"connection_state":"connected","connected_account":null,"matches_candidate":null,"connect_via":"api"},{"platform":"twitter","label":"X","status":"missing","handle":null,"url":null,"display_name":null,"followers":null,"verified":null,"confidence":null,"reason":null,"connected":false,"connection_state":"disconnected","connected_account":null,"matches_candidate":null,"connect_via":"api"}],"summary":{"found":3,"connected":2,"needs_review":1,"missing":1},"verify_url":"https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa","note":null,"computed_at":"2026-10-15T09:30:00.000Z"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:read"]}],"x-required-scope":"shows:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"start_account_discovery","summary":"Run account discovery for a show","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Run account discovery for a show, the same search Listener's onboarding uses: it finds the show's public accounts, checks each profile, stores the result on the show and returns the candidates with their connection state. Nothing is connected.\n\nNeeds `\"confirm\": true`: every run is metered (web search, model and scraper credits) and capped per show, and a show that already has a result may get it back without a new search. A `running` status means the search is still going: read `GET /v1/shows/{show_id}/account-discovery` a minute later. A dry run returns the request without starting anything.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `\"confirm\": true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `shows:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."},"confirm":{"default":false,"type":"boolean","description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"account_discovery","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/pQ7sHt2Lw9XcV4bN1mRa","id":"pQ7sHt2Lw9XcV4bN1mRa","method":"http","written":{"uid":"pQ7sHt2Lw9XcV4bN1mRa"},"warnings":["Discovery already ran for this show; the app may return its stored result instead of searching again."],"urls":{"app":"https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa","public":null},"error":null,"data":{"show_id":"pQ7sHt2Lw9XcV4bN1mRa","previous_status":"done","previous_runs":1,"verify_url":"https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa","status":"would-run"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/shows/SHOW_ID/account-discovery\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/integrations/{platform}":{"put":{"operationId":"connect_integration","summary":"Connect a platform to a show","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"platform","in":"path","required":true,"schema":{"enum":["instagram","tiktok","twitter","facebook","threads","linkedin","simplecast","youtube","instagramBusiness","spotify","applePodcasts"],"type":"string"},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Connect a platform to a show the same way the Listener apps' Integrations page does: the account is seeded, its first data refresh runs and it is listed on the show's public page. The response says whether it connected, which account, and whether the first refresh finished (`refreshed`).\n\nPublic-profile platforms (`instagram`, `tiktok`, `twitter`, `facebook`, `threads`, `linkedin`) take `handle` (e.g. `dugoutdaily`) or the profile `url`; LinkedIn needs the URL. `simplecast` takes `api_key` and optionally `podcast_id`; the key is never returned. `youtube`, `instagramBusiness`, `spotify` and `applePodcasts` need a person to sign in (Google or Meta sign-in, or the Listener browser extension) and answer 400 `oauth_required` with `connect_url`, the page to send them to. Connecting a platform that is connected to another account replaces it (a warning says so). Emits `integration.connected`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `shows:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Public URL handle (lowercase, hyphens)."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"podcast_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"integration","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/pQ7sHt2Lw9XcV4bN1mRa","id":"instagram","method":"http","written":{"uid":"pQ7sHt2Lw9XcV4bN1mRa","platform":"instagram","handle":"dugoutdaily","url":"https://www.instagram.com/dugoutdaily/"},"warnings":[],"urls":{"app":"https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa","public":null},"error":null,"data":{"show_id":"pQ7sHt2Lw9XcV4bN1mRa","platform":"instagram","previous_state":"connected","previous_account":"dugoutdaily","status":"would-connect"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]},"delete":{"operationId":"disconnect_integration","summary":"Disconnect a platform from a show","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"platform","in":"path","required":true,"schema":{"enum":["instagram","tiktok","twitter","facebook","threads","linkedin","simplecast","youtube","instagramBusiness","spotify","applePodcasts"],"type":"string"},"description":"A platform name (e.g. youtube, spotify, applePodcasts, instagram)."},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"name":"confirm","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Disconnect a platform from a show the same way the Integrations page does; the response includes the state and account it had. Needs `\"confirm\": true` (send `?confirm=true`): the show stops refreshing that platform until someone connects it again. Emits `integration.disconnected`.\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `?confirm=true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `shows:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"integration","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/pQ7sHt2Lw9XcV4bN1mRa","id":"instagram","method":"http","written":{"uid":"pQ7sHt2Lw9XcV4bN1mRa","platform":"instagram"},"warnings":[],"urls":{"app":"https://network.listener.com/app/integrations?show=pQ7sHt2Lw9XcV4bN1mRa","public":null},"error":null,"data":{"show_id":"pQ7sHt2Lw9XcV4bN1mRa","platform":"instagram","previous_state":"connected","previous_account":"dugoutdaily","status":"would-disconnect"},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/shows/SHOW_ID/integrations/PLATFORM?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/podcast":{"put":{"operationId":"set_podcast_identity","summary":"Set a show's podcast identity","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Set the listing ids that identify the show: `rss_url`, `apple_podcasts_id`, `spotify_id`, `podchaser_id` and `simplecast_podcast_id`, the same fields Listener stores when a show is picked during onboarding. Only the fields you send change; an empty string clears one. Ids are validated and may be sent as the platform's own URLs (`podcasts.apple.com/…/id123…`, `open.spotify.com/show/…`, `podchaser.com/podcasts/…-123`).\n\nThese are references used to match the show and its episodes. They do not connect Spotify, Apple Podcasts or Simplecast; connect Simplecast with `PUT /v1/shows/{show_id}/integrations/simplecast`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `shows:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rss_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"apple_podcasts_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"spotify_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"podchaser_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"simplecast_podcast_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"podcast_identity","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/pQ7sHt2Lw9XcV4bN1mRa","id":"pQ7sHt2Lw9XcV4bN1mRa","method":"transaction","written":{"podcastMetadata.rssUrl":"https://feeds.example.com/dugout-daily.xml","podcastMetadata.applePodcastsId":"1580012345","podcastMetadata.simplecastPodcastId":"0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f","podcastMetadata.updatedAt":"2026-10-15T09:30:00.000Z","updatedAt":"2026-10-15T09:30:00.000Z"},"warnings":[],"urls":{"app":"https://network.listener.com/app/connect?uid=pQ7sHt2Lw9XcV4bN1mRa","public":null},"error":null,"data":{"show_id":"pQ7sHt2Lw9XcV4bN1mRa","podcast":{"rss_url":"https://feeds.example.com/dugout-daily.xml","apple_podcasts_id":"1580012345","simplecast_podcast_id":"0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f"}},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["shows:write"]}],"x-required-scope":"shows:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/shows/SHOW_ID/podcast\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/podcast\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/shows/SHOW_ID/podcast\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/episodes/lookup":{"get":{"operationId":"lookup_episode","summary":"Look up an episode by a partner's identifiers","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"simplecast_episode_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"guid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"apple_episode_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"spotify_episode_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"title","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"description":"Title."},{"name":"published_on","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},{"name":"limit","in":"query","required":false,"schema":{"default":5,"maximum":20,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Find the Listener episode behind your own identifiers. Send any of `simplecast_episode_id`, `guid` (the RSS item guid), `apple_episode_id`, `spotify_episode_id`, `title` and `published_on` (`YYYY-MM-DD`). Each match returns the Listener `episode_id` (use it with every episode endpoint), its cluster id and public cluster URL, and `match` with `by` (what matched) and `confidence`:\n\n- `exact`: an id or guid stored on the episode;\n- `high`: the same title within a day of the date (or a title unique in the show when no date is sent);\n- `medium`: the same title on another day, or a near-identical title within a day;\n- `low`: a similar title within a day.\n\nA Simplecast episode id is resolved through the show's Simplecast analytics to its title and publish date, then matched, so it is never better than `high`. `best` is set only for an `exact` or `high` match that no other episode ties; otherwise review `matches`. Nothing is guessed silently: `note` explains misses.\n\n- Required scope: `episodes:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EpisodeLookupResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"episode_lookup"}}}]},"example":{"object":"episode_lookup","show_id":"pQ7sHt2Lw9XcV4bN1mRa","query":{"simplecast_episode_id":"8a1f3c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b"},"best":{"episode_id":"4rOoJ6Egrf8K2IrywzwOMk","title":"Ep. 41: Trade Deadline Winners","published_at":"2026-10-14","source_platform":"spotify","cluster_id":"cluster-4rOoJ6Egrf8K2IrywzwOMk","cluster_url":"https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-4rOoJ6Egrf8K2IrywzwOMk","match":{"by":"simplecast_episode_id+title+date","confidence":"high","score":1.0,"reasons":["same title","same day"]}},"matches":[{"episode_id":"4rOoJ6Egrf8K2IrywzwOMk","title":"Ep. 41: Trade Deadline Winners","published_at":"2026-10-14","source_platform":"spotify","cluster_id":"cluster-4rOoJ6Egrf8K2IrywzwOMk","cluster_url":"https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-4rOoJ6Egrf8K2IrywzwOMk","match":{"by":"simplecast_episode_id+title+date","confidence":"high","score":1.0,"reasons":["same title","same day"]}}],"ambiguous":false,"simplecast_episode":{"id":"8a1f3c2e-5b6d-4e7f-9a0b-1c2d3e4f5a6b","title":"Ep. 41: Trade Deadline Winners","published_at":"2026-10-14T04:00:00Z","listeners":5400},"note":null,"computed_at":"2026-10-15T09:30:00.000Z"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["episodes:read"]}],"x-required-scope":"episodes:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/episodes/lookup\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/episodes/lookup\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/episodes/lookup\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/shows/{show_id}/auto-build":{"get":{"operationId":"get_auto_build","summary":"Retrieve a show's auto-build setting and statuses","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"name":"limit","in":"query","required":false,"schema":{"default":20,"maximum":100,"minimum":1,"type":"integer"},"description":"Maximum number of items to return."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"The show's auto-build setting and recent per-episode build statuses. `mode` is `off`, `suggest` (posts are recorded for review) or `auto` (the sure ones are added to the episode's cluster); `legacy` marks a mode read from the older on/off switch. `statuses` lists the latest episodes first (`building`, `ready`, `built`, `nothing`, `failed`, `accepted`, `dismissed`) with cluster ids and reasons; `counts` covers every stored status.\n\nNew episodes are picked up by Listener's hourly auto-build run (episodes from the last 14 days without a cluster). To build an episode the moment you publish it, call `POST /v1/cluster-builds` with `scope: \"episodes\"` and its episode id.\n\n- Required scope: `clusters:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AutoBuildResult"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"auto_build"}}}]},"example":{"object":"auto_build","show_id":"pQ7sHt2Lw9XcV4bN1mRa","mode":"suggest","legacy":false,"enabled_at":"2026-10-01T15:02:11.000Z","updated_at":"2026-10-01T15:02:11.000Z","last_run":{"run_id":"run_8Hq2Lm4Tz9","trigger":"cron","at":"2026-10-15T09:30:00.000Z","episodes":2},"counts":{"built":1,"ready":1},"statuses":[{"episode_id":"4rOoJ6Egrf8K2IrywzwOMk","status":"ready","title":"Ep. 41: Trade Deadline Winners","published_at":"2026-10-14T00:00:00.000Z","cluster_id":null,"cluster_url":null,"added_count":null,"reason":null,"error":null,"trigger":"cron","mode":"suggest","updated_at":"2026-10-15T09:30:00.000Z"},{"episode_id":"2bN8vC4xZ1qW7eR5tY3uIo","status":"built","title":"Ep. 40: Bullpen Math","published_at":"2026-10-07T00:00:00.000Z","cluster_id":"cluster-2bN8vC4xZ1qW7eR5tY3uIo","cluster_url":"https://listener.com/cluster/pQ7sHt2Lw9XcV4bN1mRa_cluster-2bN8vC4xZ1qW7eR5tY3uIo","added_count":6,"reason":null,"error":null,"trigger":"cron","mode":"auto","updated_at":"2026-10-08T08:02:10.000Z"}],"schedule":"In 'suggest' and 'auto' modes Listener's hourly auto-build run looks for episodes from the last 14 days that have no cluster yet: 'suggest' records posts to review, 'auto' adds the sure ones to a cluster. To build an episode the moment it is published, start a cluster build for that episode.","computed_at":"2026-10-15T09:30:00.000Z"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:read"]}],"x-required-scope":"clusters:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/shows/SHOW_ID/auto-build\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/auto-build\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/shows/SHOW_ID/auto-build\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"put":{"operationId":"set_auto_build_mode","summary":"Set a show's auto-build mode","tags":["Partner integrations"],"parameters":[{"name":"show_id","in":"path","required":true,"schema":{"type":"string"},"description":"A show id in this workspace (see GET /v1/shows)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Turn auto-build on (`suggest` or `auto`) or `off` for a show, as the Episodes page does, and return the previous and new mode. The hourly auto-build run then picks up new episodes; for an immediate build after publishing call `POST /v1/cluster-builds`. `draft` is refused: it is a per-build policy the hourly run never uses.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `clusters:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"enum":["off","suggest","auto","draft"],"type":"string","description":"How the change applies (see the operation description)."},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["mode"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"auto_build","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/pQ7sHt2Lw9XcV4bN1mRa","id":"pQ7sHt2Lw9XcV4bN1mRa","method":"transaction","written":{"profile.aiAutomationEnabled":false,"profile.autoBuild.mode":"auto","profile.autoBuild.updatedAt":"2026-10-15T09:30:00.000Z","users/pQ7sHt2Lw9XcV4bN1mRa/autoBuildSettings/current":{"mode":"auto","updatedAt":"2026-10-15T09:30:00.000Z"}},"warnings":[],"urls":{"app":"https://network.listener.com/app/episodes?uid=pQ7sHt2Lw9XcV4bN1mRa","public":null},"error":null,"data":{"show_id":"pQ7sHt2Lw9XcV4bN1mRa","mode":"auto","previous_mode":"suggest","schedule":"In 'suggest' and 'auto' modes Listener's hourly auto-build run looks for episodes from the last 14 days that have no cluster yet: 'suggest' records posts to review, 'auto' adds the sure ones to a cluster. To build an episode the moment it is published, start a cluster build for that episode."},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["clusters:write"]}],"x-required-scope":"clusters:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PUT \"https://api.listener.com/v1/shows/SHOW_ID/auto-build\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mode\": \"off\", \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/shows/SHOW_ID/auto-build\", {\n  method: \"PUT\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"mode\": \"off\", \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.put(\n    \"https://api.listener.com/v1/shows/SHOW_ID/auto-build\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'mode': 'off', 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/external-delivery":{"get":{"operationId":"list_campaign_external_delivery","summary":"List a campaign's external ad-server delivery","tags":["Partner integrations"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"enum":["adswizz","audioserve","other"],"type":"string"},{"type":"null"}],"default":null}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Delivery reported by external ad servers (AdsWizz, AudioServe or other) on a campaign: impressions and optional listeners per day or period, per slot and show, newest first, with `meta.totals_by_source`. These are true counts from the ad server, kept apart: they are never added to Listener reach, impressions or EMV.\n\n- Required scope: `campaigns:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/ExternalDeliveryRow"},{"type":"object","required":["object"],"properties":{"object":{"type":"string","const":"external_delivery"}}}]}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"campaign_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Campaign Title"},"row_count":{"default":0,"title":"Row Count","type":"integer"},"totals_by_source":{"additionalProperties":{"$ref":"#/components/schemas/ExternalDeliveryTotals"},"title":"Totals By Source","type":"object"},"note":{"description":"These are counts reported by the ad server; they are never added to Listener reach totals.","title":"Note","type":"string"},"computed_at":{"title":"Computed At","type":"string"}},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/campaigns/Xb3kQ9LmT2vWc8Rz1PaE/external-delivery","data":[{"object":"external_delivery","id":"xd_7Rk2Lq9ZpT4mW8cN1vBd","source":"adswizz","label":"Dugout Daily mid-roll","slot_id":"ep_1760430000000_k2m9qa","show_id":"pQ7sHt2Lw9XcV4bN1mRa","date":"2026-10-14","start_date":null,"end_date":null,"impressions":18250,"listeners":11900,"note":null,"created_at":"2026-10-15T09:30:00.000Z","updated_at":"2026-10-15T09:30:00.000Z","created_by":"api"},{"object":"external_delivery","id":"xd_3Hf6Xs1QaY9eK2uJ5rLm","source":"audioserve","label":"Week 41 network run","slot_id":null,"show_id":"Hc4pWq8ZtLm2Xv7Rb1Ny","date":null,"start_date":"2026-10-06","end_date":"2026-10-12","impressions":64000,"listeners":null,"note":null,"created_at":"2026-10-15T09:30:00.000Z","updated_at":"2026-10-15T09:30:00.000Z","created_by":"api"}],"has_more":false,"next_cursor":null,"meta":{"campaign_id":"Xb3kQ9LmT2vWc8Rz1PaE","campaign_title":"Acme Coffee Q4 Fall Flight","row_count":2,"totals_by_source":{"adswizz":{"rows":1,"impressions":18250,"listeners":11900},"audioserve":{"rows":1,"impressions":64000,"listeners":null}},"note":"Counts reported by the ad server (AdsWizz, AudioServe …). They are stored as reported and are never added to Listener reach, impressions or EMV totals.","computed_at":"2026-10-15T09:30:00.000Z","total":2}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:read"]}],"x-required-scope":"campaigns:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"add_campaign_external_delivery","summary":"Record external ad-server delivery on a campaign","tags":["Partner integrations"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Record ad-server delivery on a campaign. Each row has `source` (`adswizz`, `audioserve`, `other`), either `date` or `start_date` + `end_date`, `impressions`, and optionally `listeners`, `slot_id`, `show_id`, `label` and `note`. A row with the same source, slot, show and day (or period) as a stored row updates it instead of adding a duplicate, so re-sending a day is safe. Up to 500 rows per request and 2,000 per campaign. The response lists the row ids added and updated and the totals per source. Emits `campaign.updated`. These counts are never added to Listener reach totals.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `campaigns:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"items":{"$ref":"#/components/schemas/ExternalDeliveryRowInput"},"maxItems":500,"minItems":1,"type":"array"},"dry_run":{"default":false,"type":"boolean","description":"true returns exactly what would be written without writing anything (the API's test mode)."}},"additionalProperties":false,"required":["rows"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"external_delivery","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/uJm8Fq1kT0bYwZ3xA9cD/campaigns/Xb3kQ9LmT2vWc8Rz1PaE","id":"Xb3kQ9LmT2vWc8Rz1PaE","method":"transaction","written":{"externalDelivery":"<3 rows>","rows_written":[{"source":"adswizz","label":"Dugout Daily mid-roll","slot_id":"ep_1760430000000_k2m9qa","show_id":"pQ7sHt2Lw9XcV4bN1mRa","date":"2026-10-15","start_date":null,"end_date":null,"impressions":17480,"listeners":11320,"note":null,"id":"xd_9Tn4Pw2ZcV7bQ1mR8sKe","created_at":"2026-10-15T09:30:00.000Z","updated_at":"2026-10-15T09:30:00.000Z","created_by":"api"}],"updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=Xb3kQ9LmT2vWc8Rz1PaE&uid=uJm8Fq1kT0bYwZ3xA9cD","public":"https://network.listener.com/northwind-audio/campaigns/Xb3kQ9LmT2vWc8Rz1PaE"},"error":null,"data":{"campaign_id":"Xb3kQ9LmT2vWc8Rz1PaE","added":["xd_9Tn4Pw2ZcV7bQ1mR8sKe"],"updated":[],"row_count":3,"totals_by_source":{"adswizz":{"rows":2,"impressions":35730,"listeners":23220},"audioserve":{"rows":1,"impressions":64000,"listeners":null}},"note":"Counts reported by the ad server (AdsWizz, AudioServe …). They are stored as reported and are never added to Listener reach, impressions or EMV totals."},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"rows\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"rows\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'rows': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/campaigns/{campaign_id}/external-delivery/{row_id}":{"delete":{"operationId":"delete_campaign_external_delivery","summary":"Delete an external delivery row","tags":["Partner integrations"],"parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"},"description":"Campaign id (see GET /v1/campaigns)."},{"name":"row_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"dry_run","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"true returns exactly what would be written without writing anything (the API's test mode)."},{"name":"confirm","in":"query","required":false,"schema":{"default":false,"type":"boolean"},"description":"Must be true to apply destructive or metered changes; without it the API answers 409 with a preview."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Delete one external delivery row (`xd_…`) from a campaign. Needs `\"confirm\": true` (send `?confirm=true`); there is no undo. Emits `campaign.updated`.\n\n- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Requires `?confirm=true`; without it the API answers 409 `confirmation_required` with the exact `preview`.\n- Required scope: `campaigns:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WriteResultResponse"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"external_delivery","would_write":{"ok":true,"dry_run":true,"auth_mode":"api_key","path":"users/uJm8Fq1kT0bYwZ3xA9cD/campaigns/Xb3kQ9LmT2vWc8Rz1PaE","id":"Xb3kQ9LmT2vWc8Rz1PaE","method":"transaction","written":{"removed":{"id":"xd_7Rk2Lq9ZpT4mW8cN1vBd","source":"adswizz","label":"Dugout Daily mid-roll","slot_id":"ep_1760430000000_k2m9qa","show_id":"pQ7sHt2Lw9XcV4bN1mRa","date":"2026-10-14","start_date":null,"end_date":null,"impressions":18250,"listeners":11900,"note":null,"created_at":"2026-10-15T09:30:00.000Z","updated_at":"2026-10-15T09:30:00.000Z","created_by":"api"},"externalDelivery":"<1 row>","updatedAt":"<serverTimestamp>"},"warnings":[],"urls":{"app":"https://network.listener.com/app/campaign?id=Xb3kQ9LmT2vWc8Rz1PaE&uid=uJm8Fq1kT0bYwZ3xA9cD","public":"https://network.listener.com/northwind-audio/campaigns/Xb3kQ9LmT2vWc8Rz1PaE"},"error":null,"data":{"campaign_id":"Xb3kQ9LmT2vWc8Rz1PaE","deleted_row_id":"xd_7Rk2Lq9ZpT4mW8cN1vBd","row_count":1,"totals_by_source":{"audioserve":{"rows":1,"impressions":64000,"listeners":null}},"confirm_required":true},"replayed":false}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["campaigns:write"]}],"x-required-scope":"campaigns:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery/ROW_ID?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery/ROW_ID?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/campaigns/CAMPAIGN_ID/external-delivery/ROW_ID?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints":{"get":{"operationId":"list_webhook_endpoints","summary":"List webhook endpoints","tags":["Webhooks & events"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"- Required scope: `webhooks:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/webhook-endpoints","data":[{"object":"webhook_endpoint","id":"we_3Eg9g0CxU0cF8kZ1wT1t","url":"https://example.com/the-draft-room/webhooks","description":"Production listener","enabled_events":["campaign.updated","cluster.nodes_added"],"status":"enabled","disabled_reason":null,"secret_last4":"Q2x9","api_version":"2026-10-14","created_at":"2026-10-14T09:30:00Z","updated_at":"2026-10-14T09:30:00Z"}],"has_more":false,"next_cursor":null,"meta":{}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:read"]}],"x-required-scope":"webhooks:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/webhook-endpoints\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/webhook-endpoints\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"post":{"operationId":"create_webhook_endpoint","summary":"Create a webhook endpoint","tags":["Webhooks & events"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Returns the signing `secret` (whsec_…) once. Up to 16 endpoints per workspace.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS URL that receives POSTed events."},"enabled_events":{"items":{"type":"string"},"type":"array","description":"Event types to deliver, or [\"*\"] for all. See GET /v1/event-types."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text note shown in the dashboard."},"dry_run":{"type":"boolean","default":false,"description":"Validate and return what would be written without calling the service."}},"additionalProperties":false,"required":["url","enabled_events"]}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_endpoint","would_write":{"method":"POST","path":"/v1/webhook-endpoints","params":{"enabled_events":["*"],"url":"https://example.com/the-overtime-report"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/webhook-endpoints\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"url\": \"URL\", \"enabled_events\": [], \"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"url\": \"URL\", \"enabled_events\": [], \"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/webhook-endpoints\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'url': 'URL', 'enabled_events': [], 'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints/{endpoint_id}":{"get":{"operationId":"get_webhook_endpoint","summary":"Retrieve a webhook endpoint","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"- Required scope: `webhooks:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"},"example":{"object":"webhook_endpoint","id":"we_3Eg9g0CxU0cF8kZ1wT1t","url":"https://example.com/the-draft-room/webhooks","description":"Production listener","enabled_events":["campaign.updated","cluster.nodes_added"],"status":"enabled","disabled_reason":null,"secret_last4":"Q2x9","api_version":"2026-10-14","created_at":"2026-10-14T09:30:00Z","updated_at":"2026-10-14T09:30:00Z"}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:read"]}],"x-required-scope":"webhooks:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]},"patch":{"operationId":"update_webhook_endpoint","summary":"Update a webhook endpoint","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"New HTTPS URL."},"enabled_events":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"Event types to deliver, or [\"*\"]."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text note."},"disabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"true pauses deliveries; false re-enables the endpoint."},"dry_run":{"type":"boolean","default":false,"description":"Validate and return what would be written without calling the service."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_endpoint","would_write":{"method":"PATCH","path":"/v1/webhook-endpoints/we_probe","params":{"endpoint_id":"we_probe","description":"probe"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\", {\n  method: \"PATCH\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.patch(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]},"delete":{"operationId":"delete_webhook_endpoint","summary":"Delete a webhook endpoint","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Validate and return what would be written without calling the service."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"- Send `?dry_run=true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_endpoint","would_write":{"method":"DELETE","path":"/v1/webhook-endpoints/we_probe","params":{"endpoint_id":"we_probe"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X DELETE \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID?dry_run=true\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID?dry_run=true\", {\n  method: \"DELETE\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.delete(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID?dry_run=true\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints/{endpoint_id}/roll-secret":{"post":{"operationId":"roll_webhook_endpoint_secret","summary":"Roll a webhook signing secret","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"Returns the new secret once; the previous one keeps signing until `expires_previous_at`.\n\n- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expire_previous_in_hours":{"type":"integer","default":24,"description":"Hours the previous secret keeps signing (0–168)."},"dry_run":{"type":"boolean","default":false,"description":"Validate and return what would be written without calling the service."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookEndpoint"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_endpoint","would_write":{"method":"POST","path":"/v1/webhook-endpoints/we_probe/roll-secret","params":{"endpoint_id":"we_probe"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/roll-secret\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/roll-secret\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/roll-secret\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints/{endpoint_id}/secret":{"get":{"operationId":"reveal_webhook_endpoint_secret","summary":"Reveal a webhook signing secret","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"$ref":"#/components/parameters/ListenerVersion"}],"description":"The endpoint's current signing secret (`whsec_…`), as the dashboard's \"Reveal\" shows it, plus `previous_secret_expires_at` while a rolled secret still signs. Needs `webhooks:write` because the secret lets its holder forge deliveries. Never cached (`Cache-Control: no-store`, no `ETag`).\n\n- Required scope: `webhooks:write`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointSecret"},"example":{"object":"webhook_endpoint_secret","id":"we_3Eg9g0CxU0cF8kZ1wT1t","secret":"whsec_EXAMPLEonlyNotARealSecret0000000000000","secret_last4":"0000","previous_secret_expires_at":null}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/secret\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/secret\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/secret\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints/{endpoint_id}/test":{"post":{"operationId":"send_webhook_endpoint_test","summary":"Send a test event","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"event_type":{"type":"string","default":"webhook_endpoint.test","description":"Event type to send."},"dry_run":{"type":"boolean","default":false,"description":"Validate and return what would be written without calling the service."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookDelivery"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_delivery","would_write":{"method":"POST","path":"/v1/webhook-endpoints/we_probe/test","params":{"endpoint_id":"we_probe"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/test\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/test\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/test\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/webhook-endpoints/{endpoint_id}/deliveries":{"get":{"operationId":"list_webhook_deliveries","summary":"List recent deliveries","tags":["Webhooks & events"],"parameters":[{"name":"endpoint_id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook endpoint id (we_…)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"- Required scope: `webhooks:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/webhook-endpoints/we_3Eg9g0CxU0cF8kZ1wT1t/deliveries","data":[{"object":"webhook_delivery","id":"wd_6Ee1BpU8yE0zQ3sJ1pI6","endpoint_id":"we_3Eg9g0CxU0cF8kZ1wT1t","event_id":"evt_1Ch6EbG4uT9nJ2hZ4aO0","event_type":"campaign.updated","status":"succeeded","attempts":[{"at":"2026-10-14T09:30:01Z","response_status":200,"duration_ms":182}],"next_attempt_at":null,"response_status":200,"response_body_excerpt":"Our hosts react to the weekend's results and look ahead to next week.","duration_ms":182,"created_at":"2026-10-14T09:30:00Z"}],"has_more":false,"next_cursor":null,"meta":{}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:read"]}],"x-required-scope":"webhooks:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/deliveries\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/deliveries\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/webhook-endpoints/ENDPOINT_ID/deliveries\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/webhook-deliveries/{delivery_id}/retry":{"post":{"operationId":"retry_webhook_delivery","summary":"Retry a delivery","tags":["Webhooks & events"],"parameters":[{"name":"delivery_id","in":"path","required":true,"schema":{"type":"string"},"description":"Delivery id (wd_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IdempotencyKey"}],"description":"- Send `\"dry_run\": true` to get `{\"object\": \"dry_run\", \"would_write\": …}` without writing anything.\n- Required scope: `webhooks:write`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean","default":false,"description":"Validate and return what would be written without calling the service."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Idempotent-Replayed":{"$ref":"#/components/headers/Idempotent-Replayed"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookDelivery"},{"$ref":"#/components/schemas/DryRun"}]},"example":{"object":"dry_run","resource":"webhook_delivery","would_write":{"method":"POST","path":"/v1/webhook-deliveries/wd_probe/retry","params":{"delivery_id":"wd_probe"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:write"]}],"x-required-scope":"webhooks:write","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST \"https://api.listener.com/v1/webhook-deliveries/DELIVERY_ID/retry\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dry_run\": true}'"},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/webhook-deliveries/DELIVERY_ID/retry\", {\n  method: \"POST\",\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\"dry_run\": true}),\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.post(\n    \"https://api.listener.com/v1/webhook-deliveries/DELIVERY_ID/retry\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n    json={'dry_run': True},\n)\nprint(resp.json())"}]}},"/v1/events":{"get":{"operationId":"list_events","summary":"List events","tags":["Webhooks & events"],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":"Only events of this type (e.g. campaign.updated)."},{"name":"created_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":"Only events created at or after this ISO 8601 time."},{"name":"created_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":"Only events created at or before this ISO 8601 time."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size, 1–100 (default 25)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from the previous page's next_cursor."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Newest first. Events are kept for 30 days.\n\n- Required scope: `webhooks:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/events","data":[{"object":"event","id":"evt_zfCWLlsXwZVK0oolPBa7Bfx0","type":"webhook_endpoint.test","api_version":"2026-10-14","created":"2026-10-14T17:24:03Z","workspace_id":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","source":"api","data":{"object":{"object":"webhook_endpoint_test","endpoint_id":"we_icrPegpM1Yvv80hXwUjoYQZs","message":"This is a test event from Listener. Respond with any 2xx status to acknowledge it."}},"request":null}],"has_more":false,"next_cursor":null,"meta":{}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:read"]}],"x-required-scope":"webhooks:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/events\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/events\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/events\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/events/{event_id}":{"get":{"operationId":"get_event","summary":"Retrieve an event","tags":["Webhooks & events"],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string"},"description":"Event id (evt_…)."},{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"- Required scope: `webhooks:read`.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"},"example":{"object":"event","id":"evt_1Ch6EbG4uT9nJ2hZ4aO0","type":"campaign.updated","api_version":"2026-10-14","created":"2026-10-14T09:30:00Z","workspace_id":"XXfzcGxkLsQaKAvRy1SwLsZCcH78","source":"api","data":{"object":{"object":"campaign","id":"B9GpElnJc2UQ1JLfav8j","title":"Tyrell Travel — Holiday Promo"},"previous_attributes":{"title":"Power rankings, week 6"}},"request":{"id":"req_9m9ReX1wIa7Na0TpP6eG","idempotency_key":"b7c1e2a4"}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[{"bearerAuth":[]},{"basicAuth":[]},{"oauth2":["webhooks:read"]}],"x-required-scope":"webhooks:read","x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/events/EVENT_ID\" \\\n  -H \"Authorization: Bearer $LISTENER_API_KEY\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/events/EVENT_ID\", {\n  headers: { Authorization: `Bearer ${process.env.LISTENER_API_KEY}` },\n});\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/events/EVENT_ID\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LISTENER_API_KEY']}\"},\n)\nprint(resp.json())"}]}},"/v1/event-types":{"get":{"operationId":"list_event_types","summary":"List event types","tags":["Webhooks & events"],"parameters":[{"$ref":"#/components/parameters/ListenerVersion"},{"$ref":"#/components/parameters/IfNoneMatch"}],"description":"Every event type with a description and an example payload. No authentication.","responses":{"200":{"description":"OK","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"ETag":{"$ref":"#/components/headers/ETag"}},"content":{"application/json":{"schema":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventType"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"example":{"object":"list","url":"/v1/event-types","data":[{"object":"event_type","name":"campaign.created","domain":"campaign","description":"A campaign was created.","sources":["api","app"],"wildcard":true,"example":{"object":"event","id":"evt_8z4V7h1Z2d6U9p6S2y7LcCnJ","type":"campaign.created","api_version":"2026-10-14","created":"2026-10-14T09:30:00Z","workspace_id":"bPv3Ck9rB5eBiM8kE2yE","source":"app","data":{"object":{"object":"campaign","id":"Hx9pD9OyG5uTw6Qu4GdM","title":"Globex Sports — Q4 Push","description":"Host-read mid-rolls plus two YouTube integrations per show.","status":"active","start_date":"2026-10-01","end_date":"2026-12-15","brand":{"name":"Hooli Mobile","slug":"hooli-mobile","domain":"hooli-mobile.example.com","logo":"https://images.example.com/listener/81e8ed4c0aa082ba.jpg"},"goals":{"total_views":2500000,"total_budget":85000},"cluster_ids":["cluster-1uE5pXhDoQ6dXjW8nIo8Po"],"total_slots":12,"created_at":"2026-09-22T15:04:11Z","updated_at":"2026-10-14T09:29:58Z","public_url":"https://network.listener.com/northwind-audio/campaigns/Hx9pD9OyG5uTw6Qu4GdM"}},"request":null}},{"object":"event_type","name":"campaign.updated","domain":"campaign","description":"A campaign's title, description, dates, brand, goals, slots, linked clusters, exclusions or EMV settings changed.","sources":["api","app"],"wildcard":true,"example":{"object":"event","id":"evt_8z4V7h1Z2d6U9p6S2y7LcCnJ","type":"campaign.updated","api_version":"2026-10-14","created":"2026-10-14T09:30:00Z","workspace_id":"bPv3Ck9rB5eBiM8kE2yE","source":"app","data":{"object":{"object":"campaign","id":"Hx9pD9OyG5uTw6Qu4GdM","title":"Globex Sports — Q4 Push","description":"Host-read mid-rolls plus two YouTube integrations per show.","status":"active","start_date":"2026-10-01","end_date":"2026-12-15","brand":{"name":"Hooli Mobile","slug":"hooli-mobile","domain":"hooli-mobile.example.com","logo":"https://images.example.com/listener/81e8ed4c0aa082ba.jpg"},"goals":{"total_views":2500000,"total_budget":85000},"cluster_ids":["cluster-1uE5pXhDoQ6dXjW8nIo8Po"],"total_slots":12,"created_at":"2026-09-22T15:04:11Z","updated_at":"2026-10-14T09:29:58Z","public_url":"https://network.listener.com/northwind-audio/campaigns/Hx9pD9OyG5uTw6Qu4GdM"},"changed_fields":["goals","slots"],"previous_attributes":{}},"request":null}}],"has_more":false,"next_cursor":null,"meta":{}}}}},"304":{"description":"Not modified (If-None-Match matched the ETag).","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"ETag":{"$ref":"#/components/headers/ETag"}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"security":[],"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl \"https://api.listener.com/v1/event-types\""},{"lang":"JavaScript","label":"Node.js (fetch)","source":"const res = await fetch(\"https://api.listener.com/v1/event-types\");\nconst data = await res.json();"},{"lang":"Python","label":"Python (requests)","source":"import os\nimport requests\n\nresp = requests.get(\n    \"https://api.listener.com/v1/event-types\",\n)\nprint(resp.json())"}]}}},"webhooks":{"event":{"post":{"summary":"Event delivery","description":"Listener POSTs each event to your endpoint, signed with `Listener-Signature: t=<unix>,v1=<hex hmac_sha256(secret, \"{t}.{body}\")>`. Answer 2xx within 10 s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery."}}}}},"components":{"schemas":{"AccountDiscoveryResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"status":{"description":"'none' (never run), 'running', 'done' or 'failed'.","title":"Status","type":"string"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"ran_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Ran At"},"runs":{"default":0,"title":"Runs","type":"integer"},"committed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"When someone confirmed the accounts in onboarding, if they did.","title":"Committed At"},"candidates":{"items":{"$ref":"#/components/schemas/DiscoveryCandidate"},"title":"Candidates","type":"array"},"summary":{"$ref":"#/components/schemas/DiscoverySummary"},"verify_url":{"description":"Deep link to the show's integrations page in the right Listener app, for a person to review and connect accounts.","title":"Verify Url","type":"string"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"}},"required":["show_id","show_name","status","verify_url","computed_at"],"title":"AccountDiscoveryResult","type":"object"},"AccountGroupMemberModel":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"show_handle":{"default":"","title":"Show Handle","type":"string"},"platform":{"title":"Platform","type":"string"},"account_key":{"title":"Account Key","type":"string"},"account_label":{"title":"Account Label","type":"string"},"profile_url":{"default":"","title":"Profile Url","type":"string"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Updated"},"data_quality":{"default":0,"title":"Data Quality","type":"number"}},"required":["show_id","show_name","platform","account_key","account_label"],"title":"AccountGroupMemberModel","type":"object"},"AccountGroupModel":{"properties":{"group_key":{"title":"Group Key","type":"string"},"platform":{"title":"Platform","type":"string"},"platform_category":{"title":"Platform Category","type":"string"},"account_key":{"title":"Account Key","type":"string"},"account_label":{"title":"Account Label","type":"string"},"canonical_show_id":{"title":"Canonical Show Id","type":"string"},"canonical_show_name":{"title":"Canonical Show Name","type":"string"},"members":{"items":{"$ref":"#/components/schemas/AccountGroupMemberModel"},"title":"Members","type":"array"},"is_duplicate":{"title":"Is Duplicate","type":"boolean"}},"required":["group_key","platform","platform_category","account_key","account_label","canonical_show_id","canonical_show_name","members","is_duplicate"],"title":"AccountGroupModel","type":"object"},"ActivityEvent":{"description":"One feed entry: ``episode`` (a linked episode aired), ``content`` (clips/posts per day + platform) or ``flight`` (start/end date).","properties":{"type":{"title":"Type","type":"string"},"key":{"title":"Key","type":"string"},"day":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Day"},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"At"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"show_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Name"},"show_names":{"items":{"type":"string"},"title":"Show Names","type":"array"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"is_first":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Is First"},"clip_count":{"default":0,"title":"Clip Count","type":"integer"},"post_count":{"default":0,"title":"Post Count","type":"integer"},"views":{"default":0,"title":"Views","type":"number"},"count_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Count Label"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Label"},"upcoming":{"default":false,"title":"Upcoming","type":"boolean"}},"required":["type","key"],"title":"ActivityEvent","type":"object"},"ActivityLog":{"properties":{"events":{"items":{"$ref":"#/components/schemas/ActivityEvent"},"title":"Events","type":"array"},"total_events":{"title":"Total Events","type":"integer"},"summary":{"additionalProperties":true,"title":"Summary","type":"object"}},"required":["events","total_events","summary"],"title":"ActivityLog","type":"object"},"AirCheckGroup":{"properties":{"key":{"title":"Key","type":"string"},"group_by":{"title":"Group By","type":"string"},"counts":{"additionalProperties":{"type":"integer"},"title":"Counts","type":"object"},"row_ids":{"items":{"type":"string"},"title":"Row Ids","type":"array"}},"required":["key","group_by","counts","row_ids"],"title":"AirCheckGroup","type":"object"},"AirCheckRead":{"properties":{"id":{"title":"Id","type":"string"},"start_seconds":{"default":0,"title":"Start Seconds","type":"number"},"length_seconds":{"default":0,"title":"Length Seconds","type":"number"},"location_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Location Pct"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"place_index":{"title":"Place Index","type":"integer"},"place_total":{"title":"Place Total","type":"integer"},"status":{"title":"Status","type":"string"},"youtube_timestamp_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Youtube Timestamp Url"},"mention":{"additionalProperties":true,"title":"Mention","type":"object"}},"required":["id","place_index","place_total","status"],"title":"AirCheckRead","type":"object"},"AirCheckRow":{"properties":{"id":{"title":"Id","type":"string"},"campaign_id":{"title":"Campaign Id","type":"string"},"campaign_title":{"default":"","title":"Campaign Title","type":"string"},"campaign_type":{"default":"","title":"Campaign Type","type":"string"},"campaign_sub":{"default":"","title":"Campaign Sub","type":"string"},"advertiser":{"title":"Advertiser","type":"string"},"brand_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Slug"},"brand_logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Logo"},"show":{"title":"Show","type":"string"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"show_image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Image"},"publish_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Publish Date"},"geo":{"default":"US","title":"Geo","type":"string"},"episode":{"title":"Episode","type":"string"},"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Id"},"episode_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Url"},"cluster_id":{"title":"Cluster Id","type":"string"},"cluster_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Public Url"},"campaign_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Campaign Public Url"},"targets":{"items":{"$ref":"#/components/schemas/AirCheckTarget"},"title":"Targets","type":"array"},"platforms":{"items":{"type":"string"},"title":"Platforms","type":"array"},"status":{"enum":["detected","missing","pending","blocked","excluded"],"title":"Status","type":"string"},"transcript_available":{"default":false,"title":"Transcript Available","type":"boolean"},"needs_aircheck":{"default":false,"title":"Needs Aircheck","type":"boolean"},"is_excluded":{"default":false,"title":"Is Excluded","type":"boolean"},"scan_blocked_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Scan Blocked Reason"},"episode_length_seconds":{"default":0,"title":"Episode Length Seconds","type":"number"},"node_reach":{"default":0,"title":"Node Reach","type":"number"},"start_seconds":{"default":0,"title":"Start Seconds","type":"number"},"length_seconds":{"default":0,"title":"Length Seconds","type":"number"},"location_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Location Pct"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Unit"},"place_total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Place Total"},"group_count":{"default":0,"title":"Group Count","type":"integer"},"mentions":{"items":{"additionalProperties":true,"type":"object"},"title":"Mentions","type":"array"},"ad_reads":{"items":{"$ref":"#/components/schemas/AirCheckRead"},"title":"Ad Reads","type":"array"}},"required":["id","campaign_id","advertiser","show","episode","cluster_id","status"],"title":"AirCheckRow","type":"object"},"AirCheckTarget":{"properties":{"platform":{"title":"Platform","type":"string"},"label":{"title":"Label","type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"node_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Node Id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"duration_seconds":{"default":0,"title":"Duration Seconds","type":"number"},"views":{"default":0,"title":"Views","type":"number"},"analyzed":{"default":false,"title":"Analyzed","type":"boolean"}},"required":["platform","label"],"title":"AirCheckTarget","type":"object"},"AircheckExcerpt":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"campaign_title":{"title":"Campaign Title","type":"string"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Name"},"source":{"description":"'audio' | 'youtube'.","title":"Source","type":"string"},"text":{"title":"Text","type":"string"},"truncated":{"default":false,"title":"Truncated","type":"boolean"}},"required":["campaign_id","campaign_title","source","text"],"title":"AircheckExcerpt","type":"object"},"AutoBuildResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"mode":{"enum":["off","suggest","auto","draft"],"title":"Mode","type":"string"},"legacy":{"default":false,"description":"True when the mode comes from the older on/off automation switch (reads as 'auto').","title":"Legacy","type":"boolean"},"enabled_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Enabled At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"last_run":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Last Run"},"counts":{"additionalProperties":{"type":"integer"},"description":"Status → number of episodes, across every stored status.","title":"Counts","type":"object"},"statuses":{"description":"Most recent per-episode statuses first.","items":{"$ref":"#/components/schemas/AutoBuildStatusRow"},"title":"Statuses","type":"array"},"schedule":{"description":"How new episodes are picked up.","title":"Schedule","type":"string"},"computed_at":{"title":"Computed At","type":"string"}},"required":["show_id","mode","schedule","computed_at"],"title":"AutoBuildResult","type":"object"},"AutoBuildStatusRow":{"properties":{"episode_id":{"title":"Episode Id","type":"string"},"status":{"description":"building, ready, built, nothing, failed, accepted or dismissed.","title":"Status","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"cluster_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Url"},"added_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Added Count"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Why nothing was built (status 'nothing').","title":"Reason"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"What went wrong (status 'failed').","title":"Error"},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Trigger"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mode"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["episode_id","status"],"title":"AutoBuildStatusRow","type":"object"},"AutoGate":{"properties":{"auto_off":{"default":false,"description":"True when this show's AI picks aren't accurate enough to add posts by themselves; everything waits for review.","title":"Auto Off","type":"boolean"},"basis":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"measured (checked against the show's recent clusters) | insufficient (too few to check) | default.","title":"Basis"},"precision":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Share of the AI's sure picks the show's editors had also clustered, in the check.","title":"Precision"},"picks":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Picks"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Plain-English explanation to relay.","title":"Reason"}},"title":"AutoGate","type":"object"},"BenchmarkPeriod":{"properties":{"label":{"default":"","title":"Label","type":"string"},"peer_count":{"default":0,"title":"Peer Count","type":"integer"},"sufficient":{"default":false,"description":"At least 3 same-format peers in the period.","title":"Sufficient","type":"boolean"},"medians":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"title":"Medians","type":"object"},"deltas":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":"Percent vs the peer median.","title":"Deltas","type":"object"},"median_counts":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"title":"Median Counts","type":"object"}},"title":"BenchmarkPeriod","type":"object"},"BenchmarkSummary":{"properties":{"population_size":{"default":0,"title":"Population Size","type":"integer"},"years":{"items":{"type":"integer"},"title":"Years","type":"array"},"median_metrics":{"anyOf":[{"additionalProperties":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object"},"type":"object"},{"type":"null"}],"default":null,"title":"Median Metrics"},"breakout_count":{"default":0,"title":"Breakout Count","type":"integer"}},"title":"BenchmarkSummary","type":"object"},"BrandCollabInput":{"additionalProperties":false,"properties":{"name":{"default":"","type":"string"},"url":{"default":"","type":"string"},"logo_url":{"default":"","type":"string"},"description":{"default":"","type":"string"}},"type":"object"},"BrandInput":{"additionalProperties":false,"description":"``brandDetails`` for a campaign (write-spec §2.1 / §2.6).\n\nA bare string is accepted as the brand name (``brand=\"Acme\"``) since that is\nwhat an assistant naturally passes.","properties":{"name":{"default":"","type":"string"},"contact":{"default":"","type":"string"},"notes":{"default":"","type":"string"},"logo":{"default":"","type":"string"},"domain":{"default":"","type":"string"},"invite_email":{"default":"","type":"string"}},"type":"object"},"BrandRow":{"properties":{"slug":{"title":"Slug","type":"string"},"name":{"title":"Name","type":"string"},"normalized_name":{"default":"","title":"Normalized Name","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Logo"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Notes"},"has_contact":{"default":false,"title":"Has Contact","type":"boolean"},"has_brand_doc":{"default":false,"description":"True when a campaignBrands/{slug} canonical doc exists.","title":"Has Brand Doc","type":"boolean"},"campaign_ids":{"items":{"type":"string"},"title":"Campaign Ids","type":"array"},"campaign_count":{"default":0,"title":"Campaign Count","type":"integer"},"status_counts":{"additionalProperties":{"type":"integer"},"title":"Status Counts","type":"object"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_count":{"default":0,"title":"Show Count","type":"integer"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Used At"},"totals":{"additionalProperties":true,"description":"brand_campaign_report totals: reach by category, budget, planned impressions, expected/delivered CPM.","title":"Totals","type":"object"},"emv_total":{"default":0,"title":"Emv Total","type":"number"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"}},"required":["slug","name","precision","app_url"],"title":"BrandRow","type":"object"},"BuildCounts":{"properties":{"built":{"default":0,"title":"Built","type":"integer"},"ready":{"default":0,"title":"Ready","type":"integer"},"nothing":{"default":0,"title":"Nothing","type":"integer"},"failed":{"default":0,"title":"Failed","type":"integer"},"skipped":{"default":0,"title":"Skipped","type":"integer"}},"title":"BuildCounts","type":"object"},"BuildEpisode":{"properties":{"id":{"title":"Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"has_cluster":{"default":false,"title":"Has Cluster","type":"boolean"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"build_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"AI build status for this episode: building | ready (suggestions waiting) | built | accepted | nothing | failed | dismissed.","title":"Build Status"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"stored (in the show's saved feed) | live (newest episodes read from the platform feed, not saved yet) | catalog (older episodes from the show's loaded back catalogue).","title":"Source"}},"required":["id"],"title":"BuildEpisode","type":"object"},"BuildEpisodesResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"configured":{"title":"Configured","type":"boolean"},"episodes":{"items":{"$ref":"#/components/schemas/BuildEpisode"},"title":"Episodes","type":"array"},"total":{"default":0,"title":"Total","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","configured","computed_at","cache_age_seconds"],"title":"BuildEpisodesResult","type":"object"},"BuildJob":{"properties":{"job_id":{"title":"Job Id","type":"string"},"status":{"description":"queued | running | done | failed | cancelled.","title":"Status","type":"string"},"scope":{"$ref":"#/components/schemas/BuildScope"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mode"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"web | agent | mcp | cron.","title":"Source"},"total":{"default":0,"title":"Total","type":"integer"},"done":{"default":0,"title":"Done","type":"integer"},"progress_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Progress Pct"},"counts":{"$ref":"#/components/schemas/BuildCounts"},"current_episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Current Episode Id"},"current_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Current Title"},"phase":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The step the job is on, in plain English (e.g. 'Reading posts from 9 accounts…').","title":"Phase"},"auto_gate":{"anyOf":[{"$ref":"#/components/schemas/AutoGate"},{"type":"null"}],"default":null,"description":"Whether auto mode may add posts for this show, and why not."},"credits_used":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Credits Used"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Started At"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Finished At"},"heartbeat_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Heartbeat At"},"stalled":{"default":false,"description":"Running but no heartbeat for over 10 minutes (the hourly cron resumes it).","title":"Stalled","type":"boolean"}},"required":["job_id","status","scope"],"title":"BuildJob","type":"object"},"BuildOutcome":{"properties":{"episode_id":{"title":"Episode Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"status":{"description":"built | ready | nothing | failed | skipped | building …","title":"Status","type":"string"},"count":{"default":0,"description":"Suggested posts on the episode's status doc.","title":"Count","type":"integer"},"added":{"default":0,"description":"Posts written into the cluster.","title":"Added","type":"integer"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Why nothing was found (status nothing).","title":"Reason"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Why it failed (status failed).","title":"Error"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Review Url"}},"required":["episode_id","status"],"title":"BuildOutcome","type":"object"},"BuildScope":{"properties":{"kind":{"title":"Kind","type":"string"},"from_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"From Date"},"to_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"To Date"},"episode_ids":{"items":{"type":"string"},"title":"Episode Ids","type":"array"}},"required":["kind"],"title":"BuildScope","type":"object"},"CampaignBrandRef":{"properties":{"name":{"default":"","title":"Name","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Logo"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Notes"},"has_contact":{"default":false,"title":"Has Contact","type":"boolean"},"page_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Public brand page on the network site (None without a network handle).","title":"Page Url"}},"title":"CampaignBrandRef","type":"object"},"CampaignGoals":{"properties":{"total_views":{"default":0,"title":"Total Views","type":"number"},"show_goals":{"additionalProperties":true,"title":"Show Goals","type":"object"},"total_budget":{"default":0,"title":"Total Budget","type":"number"},"show_budgets":{"additionalProperties":true,"title":"Show Budgets","type":"object"},"platform_goals":{"additionalProperties":true,"title":"Platform Goals","type":"object"}},"title":"CampaignGoals","type":"object"},"CampaignPacing":{"properties":{"total_slots":{"default":0,"title":"Total Slots","type":"integer"},"live_slots":{"default":0,"title":"Live Slots","type":"integer"},"expected_reach":{"default":0,"title":"Expected Reach","type":"number"},"pacing_pct":{"default":0,"title":"Pacing Pct","type":"number"},"delta":{"default":0,"title":"Delta","type":"number"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Delta Pct"},"has_live_pacing":{"default":false,"title":"Has Live Pacing","type":"boolean"},"is_ahead":{"default":false,"title":"Is Ahead","type":"boolean"},"status_label":{"default":"","title":"Status Label","type":"string"},"bar_pct":{"default":0,"title":"Bar Pct","type":"number"}},"title":"CampaignPacing","type":"object"},"CampaignReach":{"properties":{"total":{"default":0,"title":"Total","type":"number"},"youtube":{"default":0,"title":"Youtube","type":"number"},"youtube_long_form":{"default":0,"title":"Youtube Long Form","type":"number"},"youtube_shorts":{"default":0,"title":"Youtube Shorts","type":"number"},"audio":{"default":0,"title":"Audio","type":"number"},"social":{"default":0,"title":"Social","type":"number"},"long_form":{"default":0,"description":"List-page format split (nodes inferred as long-form).","title":"Long Form","type":"number"},"short_form":{"default":0,"title":"Short Form","type":"number"},"cluster_long_form":{"default":0,"title":"Cluster Long Form","type":"number"},"cluster_short_form":{"default":0,"title":"Cluster Short Form","type":"number"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"}},"title":"CampaignReach","type":"object"},"CampaignRow":{"description":"One campaigns-list row (the CSV columns plus the blocks the table shows).","properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["upcoming","active","completed"],"title":"Status","type":"string"},"status_label":{"title":"Status Label","type":"string"},"status_is_manual":{"default":false,"title":"Status Is Manual","type":"boolean"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"End Date"},"start_is_fallback":{"default":false,"title":"Start Is Fallback","type":"boolean"},"days_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Days Remaining"},"days_until_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Days Until Start"},"timing":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timing"},"brand":{"$ref":"#/components/schemas/CampaignBrandRef"},"goals":{"$ref":"#/components/schemas/CampaignGoals"},"has_goal":{"default":false,"title":"Has Goal","type":"boolean"},"goal_progress_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Goal Progress Pct"},"pacing":{"$ref":"#/components/schemas/CampaignPacing"},"budget":{"default":0,"title":"Budget","type":"number"},"expected_impressions":{"default":0,"title":"Expected Impressions","type":"number"},"expected_cpm":{"default":0,"title":"Expected Cpm","type":"number"},"delivered_cpm":{"default":0,"title":"Delivered Cpm","type":"number"},"delivered_cpm_status":{"default":"pending","title":"Delivered Cpm Status","type":"string"},"delivered_cpm_long_form":{"default":0,"title":"Delivered Cpm Long Form","type":"number"},"delivered_cpm_short_form":{"default":0,"title":"Delivered Cpm Short Form","type":"number"},"emv_total":{"default":0,"title":"Emv Total","type":"number"},"emv_enabled":{"default":false,"title":"Emv Enabled","type":"boolean"},"reach":{"$ref":"#/components/schemas/CampaignReach"},"engagement":{"default":0,"title":"Engagement","type":"number"},"engagement_rate":{"default":0,"title":"Engagement Rate","type":"number"},"linked_show_ids":{"items":{"type":"string"},"title":"Linked Show Ids","type":"array"},"linked_show_names":{"items":{"type":"string"},"title":"Linked Show Names","type":"array"},"show_count":{"default":0,"title":"Show Count","type":"integer"},"total_slots":{"default":0,"title":"Total Slots","type":"integer"},"linked_slots":{"default":0,"title":"Linked Slots","type":"integer"},"unlinked_slot_count":{"default":0,"title":"Unlinked Slot Count","type":"integer"},"live_slots":{"default":0,"title":"Live Slots","type":"integer"},"cluster_count":{"default":0,"description":"Linked clusters that were loaded.","title":"Cluster Count","type":"integer"},"clusters_missing":{"items":{"type":"string"},"title":"Clusters Missing","type":"array"},"air_checks_detected":{"default":0,"title":"Air Checks Detected","type":"integer"},"duplicate_of":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Other campaign ids with the same brand + title.","title":"Duplicate Of"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["id","title","status","status_label","brand","goals","pacing","reach","precision","app_url"],"title":"CampaignRow","type":"object"},"CampaignShowBreakdown":{"properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"metrics":{"additionalProperties":true,"title":"Metrics","type":"object"},"slots":{"default":0,"title":"Slots","type":"integer"},"linked_slots":{"default":0,"title":"Linked Slots","type":"integer"},"live_slots":{"default":0,"title":"Live Slots","type":"integer"},"pacing_expected_reach":{"default":0,"title":"Pacing Expected Reach","type":"number"},"delta_from_pacing":{"default":0,"title":"Delta From Pacing","type":"number"},"reach_goal":{"default":0,"title":"Reach Goal","type":"number"},"fulfillment_pct":{"default":0,"title":"Fulfillment Pct","type":"number"},"precision":{"default":"nodes","title":"Precision","type":"string"}},"required":["id","name","metrics"],"title":"CampaignShowBreakdown","type":"object"},"CampaignSlot":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"show_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"slot_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Slot Number"},"expected_impressions":{"default":0,"title":"Expected Impressions","type":"number"},"expected_impressions_estimated":{"default":false,"title":"Expected Impressions Estimated","type":"boolean"},"budget":{"default":0,"title":"Budget","type":"number"},"budget_pinned":{"default":false,"title":"Budget Pinned","type":"boolean"},"impressions_pinned":{"default":false,"title":"Impressions Pinned","type":"boolean"},"linked_cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Linked Cluster Id"},"linked_cluster_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Linked Cluster Name"},"linked_cluster_loaded":{"default":false,"title":"Linked Cluster Loaded","type":"boolean"},"is_live":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"None when the linked cluster was not loaded or has no nodes.","title":"Is Live"},"cluster_reach":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Cluster Reach"},"cluster_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Public Url"},"fulfillment_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Fulfillment Pct"},"excluded_node_count":{"default":0,"title":"Excluded Node Count","type":"integer"}},"title":"CampaignSlot","type":"object"},"CategoryEntry":{"properties":{"category":{"title":"Category","type":"string"},"show_count":{"title":"Show Count","type":"integer"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"}},"required":["category","show_count","show_ids"],"title":"CategoryEntry","type":"object"},"ChartSlice":{"properties":{"name":{"title":"Name","type":"string"},"value":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Value"},"color":{"title":"Color","type":"string"}},"required":["name","value","color"],"title":"ChartSlice","type":"object"},"ClusterBuildResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"configured":{"title":"Configured","type":"boolean"},"job":{"anyOf":[{"$ref":"#/components/schemas/BuildJob"},{"type":"null"}],"default":null},"finished":{"default":false,"description":"True once the job is done, failed or cancelled; stop polling then.","title":"Finished","type":"boolean"},"summary":{"default":"","description":"One plain-English line to relay to the user.","title":"Summary","type":"string"},"outcomes":{"items":{"$ref":"#/components/schemas/BuildOutcome"},"title":"Outcomes","type":"array"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"App page where the suggestions are reviewed.","title":"Review Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","configured","computed_at","cache_age_seconds"],"title":"ClusterBuildResult","type":"object"},"ClusterCustomizationInput":{"additionalProperties":false,"description":"Public cluster page overrides (``clusterCustomization.js``). Only the keys you send change.","properties":{"background_video_url":{"default":"","type":"string"},"cover_image_url":{"default":"","type":"string"},"featured_url":{"default":"","type":"string"},"co_brand":{"anyOf":[{"$ref":"#/components/schemas/CoBrandInput"},{"type":"null"}],"default":null,"description":"Co-brand shown on the public cluster page: {name, logo_url (https), href (https)}. null removes it."}},"type":"object"},"ClusterEdge":{"description":"One canvas edge between two content nodes, as stored: `source` is drawn as the parent, `target` as the child (except that an episode is always the parent).","properties":{"source":{"title":"Source","type":"string"},"target":{"title":"Target","type":"string"}},"required":["source","target"],"title":"ClusterEdge","type":"object"},"ClusterEmvEstimate":{"properties":{"total":{"title":"Total","type":"number"},"long_form_value":{"title":"Long Form Value","type":"number"},"short_form_value":{"title":"Short Form Value","type":"number"},"like_value":{"title":"Like Value","type":"number"},"comment_value":{"title":"Comment Value","type":"number"},"engagement_value":{"title":"Engagement Value","type":"number"},"nodes":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Nodes"},"includes_engagement":{"title":"Includes Engagement","type":"boolean"},"method":{"description":"'nodes' (per-node sum, the public cluster page) | 'metrics' (CPM on summary reach only).","title":"Method","type":"string"},"rates":{"$ref":"#/components/schemas/EmvRates"},"inherited_rates":{"$ref":"#/components/schemas/EmvRates"},"rates_source":{"description":"'cluster' | 'campaign' | 'network' | 'default'.","title":"Rates Source","type":"string"},"rates_campaign_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Linked campaign whose emvSettings supplied the rates, when rates_source == 'campaign'.","title":"Rates Campaign Id"}},"required":["total","long_form_value","short_form_value","like_value","comment_value","engagement_value","includes_engagement","method","rates","inherited_rates","rates_source"],"title":"ClusterEmvEstimate","type":"object"},"ClusterEpisodeRef":{"properties":{"id":{"title":"Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"}},"required":["id"],"title":"ClusterEpisodeRef","type":"object"},"ClusterFreshness":{"properties":{"kind":{"enum":["refreshed","saved","unknown"],"title":"Kind","type":"string"},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"At"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"cluster_count":{"default":0,"title":"Cluster Count","type":"integer"},"failed_node_count":{"default":0,"title":"Failed Node Count","type":"integer"},"clusters_with_errors":{"default":0,"title":"Clusters With Errors","type":"integer"},"errors":{"description":"Per-node refresh errors (capped at 20).","items":{"additionalProperties":true,"type":"object"},"title":"Errors","type":"array"}},"required":["kind"],"title":"ClusterFreshness","type":"object"},"ClusterFreshness2":{"properties":{"kind":{"default":"unknown","description":"'refreshed' (a refresh run) | 'saved' (newest node fetch stamp) | 'unknown'.","title":"Kind","type":"string"},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"At"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Refresh source when known ('manual' | 'scheduled' | …).","title":"Source"}},"title":"ClusterFreshness","type":"object"},"ClusterMeta":{"properties":{"id":{"title":"Id","type":"string"},"show":{"$ref":"#/components/schemas/ShowRef"},"title":{"title":"Title","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"internal_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Internal Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"cluster_type":{"enum":["episode","merged","manual"],"title":"Cluster Type","type":"string"},"is_merged":{"default":false,"title":"Is Merged","type":"boolean"},"is_manual":{"default":false,"title":"Is Manual","type":"boolean"},"is_empty":{"default":false,"title":"Is Empty","type":"boolean"},"contributing":{"default":true,"title":"Contributing","type":"boolean"},"episode_ids":{"items":{"type":"string"},"title":"Episode Ids","type":"array"},"episodes":{"items":{"$ref":"#/components/schemas/ClusterEpisodeRef"},"title":"Episodes","type":"array"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"episode_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Date"},"tags":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"title":"Tags","type":"object"},"customization":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Public-page overrides: background_video_url, cover_image_url, featured_url and, when set, co_brand {name, logo_url, href}.","title":"Customization"},"brand_collab":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Brand Collab"},"emv_rates":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The cluster's own stored emvRates, when set.","title":"Emv Rates"},"auto_generated":{"default":false,"title":"Auto Generated","type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App Url"}},"required":["id","show","title","cluster_type"],"title":"ClusterMeta","type":"object"},"ClusterMetrics":{"description":"The 14 reach / engagement fields ``calculateClusterMetricsFromNodes`` returns.","properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"}},"title":"ClusterMetrics","type":"object"},"ClusterNode":{"properties":{"id":{"title":"Id","type":"string"},"type":{"title":"Type","type":"string"},"platform":{"title":"Platform","type":"string"},"platform_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform Key"},"platform_raw":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform Raw"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Thumbnail"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Reach"},"reach_category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'youtube' | 'audio' | 'social' | null.","title":"Reach Category"},"reach_contributions":{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"number"}]},"title":"Reach Contributions","type":"object"},"video_form":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'long' | 'short' | null (episode anchors).","title":"Video Form"},"is_long_form":{"default":false,"title":"Is Long Form","type":"boolean"},"youtube_bucket":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Youtube Bucket"},"engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Engagement"},"engagement_breakdown":{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"number"}]},"title":"Engagement Breakdown","type":"object"},"custom_tags":{"items":{"type":"string"},"title":"Custom Tags","type":"array"},"is_sponsored":{"default":false,"title":"Is Sponsored","type":"boolean"},"sponsor_brand":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Sponsor Brand"},"is_pending":{"default":false,"title":"Is Pending","type":"boolean"},"no_data_returned":{"default":false,"title":"No Data Returned","type":"boolean"},"is_shorts":{"default":false,"title":"Is Shorts","type":"boolean"},"is_selection_episode":{"default":false,"title":"Is Selection Episode","type":"boolean"},"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Id"},"source_show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source Show Id"},"ai_relevance_score":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Ai Relevance Score"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Updated"},"podcast_downloads":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Substack cards: the downloads counted in Audio.","title":"Podcast Downloads"},"podcast_downloads_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Substack cards: 'manual' (set with `PUT /v1/shows/{show_id}/substack/downloads`), 'export' (`POST /v1/shows/{show_id}/substack/imports`) or 'api' (Substack-tracked only).","title":"Podcast Downloads Source"},"podcast_downloads_api":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Substack cards: Substack's own API count, kept even when another figure is used.","title":"Podcast Downloads Api"},"source_content_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Substack cards: the Substack post id.","title":"Source Content Id"},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The node this one hangs under on the canvas (the edge's source; an episode is always the parent of what it touches). Null for an episode anchor or a loose card. When a node has several parents this is the first; see parent_ids.","title":"Parent Id"},"parent_ids":{"description":"Every node this one hangs under (usually one).","items":{"type":"string"},"title":"Parent Ids","type":"array"},"parent_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The URL of parent_id's content, so integrations can join on links like the CSV export.","title":"Parent Url"},"child_ids":{"description":"Nodes that hang directly under this one.","items":{"type":"string"},"title":"Child Ids","type":"array"},"connected_to":{"description":"Every node joined to this one by a canvas edge, either direction: the 'Connected To' column of the clusters-all-nodes CSV export, as node ids.","items":{"type":"string"},"title":"Connected To","type":"array"},"subcluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Anchor node id of the innermost subcluster this node belongs to (an anchor belongs to its own). Null when it is in none.","title":"Subcluster Id"},"subcluster_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"That subcluster's label.","title":"Subcluster Name"},"subcluster_ids":{"description":"Every subcluster containing this node, innermost first (subclusters can nest).","items":{"type":"string"},"title":"Subcluster Ids","type":"array"},"is_subcluster_anchor":{"default":false,"description":"True when this node is a labelled subcluster anchor.","title":"Is Subcluster Anchor","type":"boolean"}},"required":["id","type","platform"],"title":"ClusterNode","type":"object"},"ClusterReportAverages":{"properties":{"avg_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Reach Per Cluster"},"avg_youtube_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Youtube Reach Per Cluster"},"avg_youtube_long_form_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Youtube Long Form Reach Per Cluster"},"avg_youtube_shorts_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Youtube Shorts Reach Per Cluster"},"avg_audio_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Audio Reach Per Cluster"},"avg_social_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Social Reach Per Cluster"},"avg_long_form_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Long Form Reach Per Cluster"},"avg_short_form_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Short Form Reach Per Cluster"},"avg_long_form_count_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Long Form Count Per Cluster"},"avg_short_form_count_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Short Form Count Per Cluster"},"avg_clips_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Clips Per Cluster"},"avg_posts_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Posts Per Cluster"},"avg_engagement_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Engagement Per Cluster"}},"title":"ClusterReportAverages","type":"object"},"ClusterReportBlock":{"description":"``buildClusterSummaryFromRows`` for one window (the episodes-page KPI bar).","properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"cluster_count":{"default":0,"description":"Reach-contributing clusters whose episode date falls in the window.","title":"Cluster Count","type":"integer"},"content_pieces":{"default":0,"title":"Content Pieces","type":"integer"},"averages":{"$ref":"#/components/schemas/ClusterReportAverages"},"growth":{"$ref":"#/components/schemas/ClusterReportGrowth"},"previous":{"$ref":"#/components/schemas/ClusterReportPrevious"},"reach_distribution":{"items":{"$ref":"#/components/schemas/ChartSlice"},"title":"Reach Distribution","type":"array"},"content_mix":{"items":{"$ref":"#/components/schemas/ChartSlice"},"title":"Content Mix","type":"array"},"has_reach_distribution_data":{"default":false,"title":"Has Reach Distribution Data","type":"boolean"},"has_content_mix_data":{"default":false,"title":"Has Content Mix Data","type":"boolean"},"counts":{"$ref":"#/components/schemas/ClusterReportCounts"}},"required":["averages","growth","previous","counts"],"title":"ClusterReportBlock","type":"object"},"ClusterReportCounts":{"properties":{"cluster_doc_count":{"default":0,"title":"Cluster Doc Count","type":"integer"},"source_cluster_count":{"default":0,"title":"Source Cluster Count","type":"integer"},"merged_cluster_count":{"default":0,"title":"Merged Cluster Count","type":"integer"},"manual_cluster_count":{"default":0,"title":"Manual Cluster Count","type":"integer"},"empty_cluster_count":{"default":0,"title":"Empty Cluster Count","type":"integer"},"unlinked_cluster_count":{"default":0,"title":"Unlinked Cluster Count","type":"integer"},"undated_cluster_count":{"default":0,"title":"Undated Cluster Count","type":"integer"},"episode_count":{"default":0,"title":"Episode Count","type":"integer"}},"title":"ClusterReportCounts","type":"object"},"ClusterReportGrowth":{"description":"Growth vs the previous window (percent; null when the previous window had no clusters).","properties":{"count_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Count Growth"},"reach_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Reach Growth"},"youtube_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Youtube Growth"},"youtube_long_form_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Youtube Long Form Growth"},"youtube_shorts_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Youtube Shorts Growth"},"audio_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Audio Growth"},"social_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Social Growth"},"long_form_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Long Form Growth"},"short_form_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Short Form Growth"},"avg_reach_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Reach Growth"},"avg_youtube_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Youtube Growth"},"avg_audio_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Audio Growth"},"avg_social_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Social Growth"},"avg_long_form_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Long Form Growth"},"avg_short_form_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Avg Short Form Growth"}},"title":"ClusterReportGrowth","type":"object"},"ClusterReportPrevious":{"properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"cluster_count":{"default":0,"title":"Cluster Count","type":"integer"}},"title":"ClusterReportPrevious","type":"object"},"ClusterReportShowBlock":{"properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"cluster_count":{"default":0,"description":"Reach-contributing clusters whose episode date falls in the window.","title":"Cluster Count","type":"integer"},"content_pieces":{"default":0,"title":"Content Pieces","type":"integer"},"averages":{"$ref":"#/components/schemas/ClusterReportAverages"},"growth":{"$ref":"#/components/schemas/ClusterReportGrowth"},"previous":{"$ref":"#/components/schemas/ClusterReportPrevious"},"reach_distribution":{"items":{"$ref":"#/components/schemas/ChartSlice"},"title":"Reach Distribution","type":"array"},"content_mix":{"items":{"$ref":"#/components/schemas/ChartSlice"},"title":"Content Mix","type":"array"},"has_reach_distribution_data":{"default":false,"title":"Has Reach Distribution Data","type":"boolean"},"has_content_mix_data":{"default":false,"title":"Has Content Mix Data","type":"boolean"},"counts":{"$ref":"#/components/schemas/ClusterReportCounts"},"show":{"$ref":"#/components/schemas/ShowRef"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"cluster_freshness":{"$ref":"#/components/schemas/ShowRefreshFreshness"}},"required":["averages","growth","previous","counts","show","cluster_freshness"],"title":"ClusterReportShowBlock","type":"object"},"ClusterRow":{"description":"One cluster as the network Clusters list shows it (summary projection only, never nodes).","properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"id":{"description":"Cluster document id (e.g. 'cluster-<episodeId>', 'cluster-merged-…', 'manual-cluster-<ts>').","title":"Id","type":"string"},"show":{"$ref":"#/components/schemas/ShowRef"},"title":{"title":"Title","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"internal_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Internal Title"},"cluster_type":{"enum":["episode","merged","manual"],"title":"Cluster Type","type":"string"},"is_merged":{"default":false,"title":"Is Merged","type":"boolean"},"is_manual":{"default":false,"title":"Is Manual","type":"boolean"},"is_empty":{"default":false,"title":"Is Empty","type":"boolean"},"contributing":{"default":true,"description":"Counted in show totals (selectReachContributingClusters): individual clusters; merged only when a show has nothing else.","title":"Contributing","type":"boolean"},"episode_ids":{"items":{"type":"string"},"title":"Episode Ids","type":"array"},"episodes":{"description":"Linked episode records (id, title, published day) when the show's episode index knows them.","items":{"$ref":"#/components/schemas/ClusterEpisodeRef"},"title":"Episodes","type":"array"},"episode_count":{"default":0,"title":"Episode Count","type":"integer"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Network-list date rule: linked episode day (merged → latest), else the stored episodePublishedAt.","title":"Published At"},"episode_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"KPI-bar date rule used by `GET /v1/clusters/report` windows.","title":"Episode Date"},"tags":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Episode tags merged onto the row: {series, guests, format}.","title":"Tags","type":"object"},"custom_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Node custom tags; only known when the full document was loaded.","title":"Custom Tags"},"sponsor_brands":{"items":{"type":"string"},"title":"Sponsor Brands","type":"array"},"brands":{"description":"Sponsored-node brands then linked campaign brands.","items":{"type":"string"},"title":"Brands","type":"array"},"node_count":{"default":0,"title":"Node Count","type":"integer"},"metrics_source":{"default":"summary","description":"'nodes' | 'summary' | 'summary_stale' | 'none'.","title":"Metrics Source","type":"string"},"summary_fresh":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Summary Fresh"},"summary_stale":{"default":false,"description":"True when the stored summary could not be verified and the full document was not fetched (beyond the recompute cap).","title":"Summary Stale","type":"boolean"},"freshness":{"$ref":"#/components/schemas/ClusterFreshness2"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"last_refresh_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refresh Attempt At"},"last_refresh_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refresh Source"},"refresh_error_count":{"default":0,"title":"Refresh Error Count","type":"integer"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"auto_generated":{"default":false,"title":"Auto Generated","type":"boolean"},"brand_collab":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Brand Collab"},"has_emv_rates":{"default":false,"title":"Has Emv Rates","type":"boolean"},"customization":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Public-page overrides: background_video_url, cover_image_url, featured_url and, when set, co_brand {name, logo_url, href}.","title":"Customization"},"linked_campaign_ids":{"items":{"type":"string"},"title":"Linked Campaign Ids","type":"array"},"linked_campaigns":{"items":{"$ref":"#/components/schemas/LinkedCampaignRef"},"title":"Linked Campaigns","type":"array"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App Url"}},"required":["id","show","title","cluster_type","freshness"],"title":"ClusterRow","type":"object"},"ClusterSourcesResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"configured":{"title":"Configured","type":"boolean"},"handles":{"items":{"$ref":"#/components/schemas/SourceHandle"},"title":"Handles","type":"array"},"enabled_count":{"default":0,"title":"Enabled Count","type":"integer"},"by_platform":{"additionalProperties":{"type":"integer"},"description":"Enabled handles per platform.","title":"By Platform","type":"object"},"window":{"anyOf":[{"$ref":"#/components/schemas/SourceWindow"},{"type":"null"}],"default":null},"learned_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Learned At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","configured","computed_at","cache_age_seconds"],"title":"ClusterSourcesResult","type":"object"},"ClusterSuggestionsResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"status":{"title":"Status","type":"string"},"total":{"title":"Total","type":"integer"},"episodes":{"items":{"$ref":"#/components/schemas/SuggestionEpisode"},"title":"Episodes","type":"array"},"has_more":{"default":false,"title":"Has More","type":"boolean"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Review Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","status","total","computed_at","cache_age_seconds"],"title":"ClusterSuggestionsResult","type":"object"},"ClusterTotals":{"description":"``aggregateClusterStats`` over the listed rows (reach-contributing clusters only).","properties":{"has_clusters":{"default":false,"title":"Has Clusters","type":"boolean"},"cluster_count":{"default":0,"description":"Every cluster document in the list (contributing or not).","title":"Cluster Count","type":"integer"},"source_cluster_count":{"default":0,"description":"Reach-contributing clusters the totals sum.","title":"Source Cluster Count","type":"integer"},"merged_cluster_count":{"default":0,"title":"Merged Cluster Count","type":"integer"},"manual_cluster_count":{"default":0,"title":"Manual Cluster Count","type":"integer"},"empty_cluster_count":{"default":0,"title":"Empty Cluster Count","type":"integer"},"unlinked_cluster_count":{"default":0,"description":"Documents with no explicit episodeIds / selectedEpisodes.","title":"Unlinked Cluster Count","type":"integer"},"episode_count":{"default":0,"title":"Episode Count","type":"integer"},"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"content_pieces":{"default":0,"title":"Content Pieces","type":"integer"},"avg_reach_per_episode":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Reach Per Episode"},"avg_reach_per_cluster":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Avg Reach Per Cluster"},"summary_fresh_count":{"default":0,"description":"Rows served from a verified v3 summary map.","title":"Summary Fresh Count","type":"integer"},"summary_recomputed_count":{"default":0,"description":"Rows whose summary was stale and were recomputed from the full document.","title":"Summary Recomputed Count","type":"integer"},"summary_stale_count":{"default":0,"description":"Rows whose summary was stale but not recomputed (beyond the recompute cap); their numbers may lag.","title":"Summary Stale Count","type":"integer"},"summary_missing_count":{"default":0,"description":"Rows with no summary and no document to recompute from.","title":"Summary Missing Count","type":"integer"}},"title":"ClusterTotals","type":"object"},"CoBrandInput":{"additionalProperties":false,"description":"A partner's co-brand on the public cluster page (stored as ``customization.coBrand``).","properties":{"name":{"description":"Partner name shown next to the show's branding (1–80 characters).","type":"string"},"logo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"https:// URL of the partner's logo."},"href":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"https:// link the co-brand points to."}},"required":["name"],"type":"object"},"Collaboration":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"default":"","title":"Name","type":"string"},"brand_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Url"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Date"},"content_link":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Content Link"},"description":{"default":"","title":"Description","type":"string"}},"title":"Collaboration","type":"object"},"CompareShowsResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"default":"reach","enum":["reach","engagement"],"title":"Metric","type":"string"},"a":{"$ref":"#/components/schemas/CompareSide"},"b":{"$ref":"#/components/schemas/CompareSide"},"head_to_head":{"items":{"$ref":"#/components/schemas/HeadToHead"},"title":"Head To Head","type":"array"},"overall_winner":{"anyOf":[{"enum":["a","b","tie"],"type":"string"},{"type":"null"}],"default":null,"title":"Overall Winner"}},"required":["window","coverage","computed_at","a","b","head_to_head"],"title":"CompareShowsResult","type":"object"},"CompareSide":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"total":{"title":"Total","type":"integer"},"youtube":{"title":"Youtube","type":"integer"},"audio":{"title":"Audio","type":"integer"},"social":{"title":"Social","type":"integer"},"newsletter":{"default":0,"title":"Newsletter","type":"integer"},"per_platform":{"additionalProperties":{"type":"integer"},"title":"Per Platform","type":"object"},"previous_total":{"title":"Previous Total","type":"integer"},"previous_youtube":{"default":0,"title":"Previous Youtube","type":"integer"},"previous_audio":{"default":0,"title":"Previous Audio","type":"integer"},"previous_social":{"default":0,"title":"Previous Social","type":"integer"},"previous_per_platform":{"additionalProperties":{"type":"integer"},"title":"Previous Per Platform","type":"object"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Growth"},"days_with_data":{"default":0,"title":"Days With Data","type":"integer"},"series":{"anyOf":[{"items":{"$ref":"#/components/schemas/TimelineRow"},"type":"array"},{"type":"null"}],"default":null,"title":"Series"}},"required":["show","total","youtube","audio","social","previous_total"],"title":"CompareSide","type":"object"},"CoverageInfo":{"description":"How much of the window actually has data (design §2).","properties":{"start":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Earliest date with data across the scoped shows.","title":"Start"},"embedded_boundary":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"today-29: dates before this come from analyticsHistory.","title":"Embedded Boundary"},"history_used":{"default":false,"title":"History Used","type":"boolean"},"previous_window_coverage_days":{"default":0,"title":"Previous Window Coverage Days","type":"integer"},"current_window_coverage_days":{"default":0,"title":"Current Window Coverage Days","type":"integer"},"growth_basis":{"default":"total","description":"'like_for_like' on windows longer than 30 days (e.g. 90d): growth compares only platforms whose data covers at least half of the previous window, both windows summed over those platforms alone.","enum":["total","like_for_like"],"title":"Growth Basis","type":"string"},"growth_platforms":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"Like-for-like windows only: the platforms the headline growth compares (empty → growth is null).","title":"Growth Platforms"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"}},"title":"CoverageInfo","type":"object"},"CpmBenchmark":{"properties":{"current_cpm":{"default":0,"title":"Current Cpm","type":"number"},"median_cpm":{"default":0,"title":"Median Cpm","type":"number"},"delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Absolute % distance from the peer median (0 inside the ±3 % neutral band).","title":"Delta Pct"},"signed_delta_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Signed Delta Pct"},"direction":{"default":"unavailable","description":"below | above | neutral | unavailable","title":"Direction","type":"string"},"sample_size":{"default":0,"title":"Sample Size","type":"integer"},"label":{"default":"","title":"Label","type":"string"},"is_renderable":{"default":false,"title":"Is Renderable","type":"boolean"}},"title":"CpmBenchmark","type":"object"},"CpmPeerRow":{"properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"status":{"enum":["upcoming","active","completed"],"title":"Status","type":"string"},"brand":{"default":"","title":"Brand","type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"delivered_cpm":{"default":0,"title":"Delivered Cpm","type":"number"},"delivered_cpm_status":{"default":"pending","title":"Delivered Cpm Status","type":"string"},"delivered_cpm_long_form":{"default":0,"title":"Delivered Cpm Long Form","type":"number"},"delivered_cpm_short_form":{"default":0,"title":"Delivered Cpm Short Form","type":"number"},"expected_cpm":{"default":0,"title":"Expected Cpm","type":"number"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"}},"required":["id","title","status","precision"],"title":"CpmPeerRow","type":"object"},"Credential":{"type":"object","properties":{"object":{"const":"credential"},"type":{"type":"string","enum":["api_key","oauth_token","firebase_id_token"]},"id":{"type":"string"},"label":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"client_id":{"type":["string","null"]}}},"DashboardShowRow":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total"},"youtube":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Youtube"},"audio":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Audio"},"social":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Social"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Growth"},"followers":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Followers"},"followers_by_platform":{"anyOf":[{"additionalProperties":{"type":"integer"},"type":"object"},{"type":"null"}],"default":null,"title":"Followers By Platform"},"demographics":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Demographics"},"connected_platforms":{"items":{"type":"string"},"title":"Connected Platforms","type":"array"}},"required":["show"],"title":"DashboardShowRow","type":"object"},"Deliverable":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"type":{"description":"audio_read | video_integration | social_clip | newsletter | custom","title":"Type","type":"string"},"label":{"default":"","title":"Label","type":"string"},"quantity":{"default":1,"title":"Quantity","type":"integer"},"manual_reach":{"default":"","description":"Custom deliverables: the reach the seller typed.","title":"Manual Reach","type":"string"},"metric_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Metric Label"},"average":{"default":0,"description":"Average reach per unit over the trailing window (from the show's clusters).","title":"Average","type":"number"},"total":{"default":0,"title":"Total","type":"number"},"verified":{"default":false,"description":"True when the average comes from measured content, not a manual figure.","title":"Verified","type":"boolean"},"count":{"default":0,"description":"Content pieces the average was built from.","title":"Count","type":"integer"}},"required":["type"],"title":"Deliverable","type":"object"},"DiscoveryCandidate":{"properties":{"platform":{"description":"instagram, tiktok, twitter, facebook, threads, linkedin or youtube.","title":"Platform","type":"string"},"label":{"title":"Label","type":"string"},"status":{"description":"'found' when discovery proposed an account, 'missing' when it found none.","title":"Status","type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handle"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"followers":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Followers"},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Verified"},"confidence":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'high', 'medium' or 'low': how sure discovery is that the account is the show's.","title":"Confidence"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Why discovery picked it (plain English).","title":"Reason"},"connected":{"description":"True when the show already has this platform connected.","title":"Connected","type":"boolean"},"connection_state":{"enum":["connected","pending","disconnected"],"title":"Connection State","type":"string"},"connected_account":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The handle or URL of the account currently connected, when known.","title":"Connected Account"},"matches_candidate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True when the connected account is this candidate; false when a different account is connected; null when either side is unknown.","title":"Matches Candidate"},"connect_via":{"description":"'api': connect with PUT /v1/shows/{show_id}/integrations/{platform}; 'app_sign_in': the person signs in from verify_url.","enum":["api","app_sign_in"],"title":"Connect Via","type":"string"}},"required":["platform","label","status","connected","connection_state","connect_via"],"title":"DiscoveryCandidate","type":"object"},"DiscoverySummary":{"properties":{"found":{"default":0,"title":"Found","type":"integer"},"connected":{"default":0,"title":"Connected","type":"integer"},"needs_review":{"default":0,"description":"Found accounts whose confidence is not 'high'.","title":"Needs Review","type":"integer"},"missing":{"default":0,"title":"Missing","type":"integer"}},"title":"DiscoverySummary","type":"object"},"DistributionEntry":{"properties":{"platform":{"title":"Platform","type":"string"},"label":{"title":"Label","type":"string"},"value":{"title":"Value","type":"integer"},"share":{"description":"Percent of the summed value (12.5 == 12.5 %).","title":"Share","type":"number"}},"required":["platform","label","value","share"],"title":"DistributionEntry","type":"object"},"DryRun":{"type":"object","required":["object","would_write"],"properties":{"object":{"type":"string","const":"dry_run"},"resource":{"type":"string"},"would_write":{"description":"The exact payload that would be written (server timestamps rendered as \"<serverTimestamp>\")."}}},"EmvBreakdown":{"properties":{"total":{"title":"Total","type":"number"},"audio_value":{"title":"Audio Value","type":"number"},"social_value":{"title":"Social Value","type":"number"},"like_value":{"title":"Like Value","type":"number"},"comment_value":{"title":"Comment Value","type":"number"},"audio_downloads":{"title":"Audio Downloads","type":"integer"},"social_impressions":{"title":"Social Impressions","type":"integer"},"likes":{"title":"Likes","type":"integer"},"comments":{"title":"Comments","type":"integer"},"rates":{"additionalProperties":{"type":"number"},"title":"Rates","type":"object"},"rates_source":{"enum":["network_default","default"],"title":"Rates Source","type":"string"},"formula":{"title":"Formula","type":"string"}},"required":["total","audio_value","social_value","like_value","comment_value","audio_downloads","social_impressions","likes","comments","rates","rates_source","formula"],"title":"EmvBreakdown","type":"object"},"EmvRates":{"properties":{"long_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Long Form Cpm"},"short_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Short Form Cpm"},"like_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Like Rate"},"comment_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Comment Rate"},"show_on_share_page":{"default":true,"title":"Show On Share Page","type":"boolean"}},"required":["long_form_cpm","short_form_cpm","like_rate","comment_rate"],"title":"EmvRates","type":"object"},"EmvRatesInput":{"additionalProperties":false,"description":"Per-cluster ``emvRates`` / network ``networkDefaultEmv``.","properties":{"long_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"short_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"like_rate":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"comment_rate":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"show_on_share_page":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null}},"type":"object"},"EmvSeriesPoint":{"properties":{"day":{"title":"Day","type":"string"},"date":{"title":"Date","type":"string"},"emv":{"description":"Cumulative EMV at that point (accrual curve).","title":"Emv","type":"number"},"period_emv":{"description":"EMV accrued inside the bucket.","title":"Period Emv","type":"number"},"emv_by_platform":{"additionalProperties":{"type":"number"},"title":"Emv By Platform","type":"object"},"period_emv_by_platform":{"additionalProperties":{"type":"number"},"title":"Period Emv By Platform","type":"object"}},"required":["day","date","emv","period_emv"],"title":"EmvSeriesPoint","type":"object"},"EmvSettingsInput":{"additionalProperties":false,"description":"Campaign ``emvSettings`` (port of ``normalizeCampaignEmvSettings``).","properties":{"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"long_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"short_form_cpm":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"like_rate":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"comment_rate":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"include_long_form":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"include_short_form":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"include_likes":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"include_comments":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null},"show_overrides":{"anyOf":[{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object"},{"type":"null"}],"default":null}},"type":"object"},"EpisodeBenchmark":{"properties":{"format":{"description":"'long' | 'short' — the episode's dominant reach format.","title":"Format","type":"string"},"year":{"title":"Year","type":"integer"},"quarter":{"title":"Quarter","type":"integer"},"counts":{"additionalProperties":{"anyOf":[{"type":"integer"},{"type":"null"}]},"title":"Counts","type":"object"},"periods":{"additionalProperties":{"$ref":"#/components/schemas/BenchmarkPeriod"},"description":"'year' and 'quarter' peer comparisons.","title":"Periods","type":"object"},"breakout":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"{multiplier, format} when the episode is ≥ 3× its format's median this year.","title":"Breakout"}},"required":["format","year","quarter"],"title":"EpisodeBenchmark","type":"object"},"EpisodeClusterSummary":{"properties":{"id":{"title":"Id","type":"string"},"cluster_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"node_count":{"default":0,"title":"Node Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"episode_ids":{"items":{"type":"string"},"title":"Episode Ids","type":"array"},"sponsor_brands":{"items":{"type":"string"},"title":"Sponsor Brands","type":"array"},"linked_campaign_ids":{"items":{"type":"string"},"title":"Linked Campaign Ids","type":"array"},"linked_campaigns":{"items":{"$ref":"#/components/schemas/LinkedCampaignRef"},"title":"Linked Campaigns","type":"array"},"freshness":{"$ref":"#/components/schemas/ClusterFreshness2"},"refresh_error_count":{"default":0,"title":"Refresh Error Count","type":"integer"},"refresh_errors":{"items":{"$ref":"#/components/schemas/RefreshError"},"title":"Refresh Errors","type":"array"},"metrics_source":{"default":"none","title":"Metrics Source","type":"string"},"summary_stale":{"default":false,"title":"Summary Stale","type":"boolean"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App Url"}},"required":["id","freshness"],"title":"EpisodeClusterSummary","type":"object"},"EpisodeGoals":{"properties":{"comparable":{"default":false,"description":"The episode has a cluster with reach, so deltas are meaningful.","title":"Comparable","type":"boolean"},"targets":{"$ref":"#/components/schemas/GoalTargets"},"deltas":{"$ref":"#/components/schemas/GoalDeltas"}},"required":["targets","deltas"],"title":"EpisodeGoals","type":"object"},"EpisodeLookupResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"query":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":"Query","type":"object"},"best":{"anyOf":[{"$ref":"#/components/schemas/EpisodeMatch"},{"type":"null"}],"default":null,"description":"Set only when the top match is exact or high confidence and unambiguous; otherwise null."},"matches":{"items":{"$ref":"#/components/schemas/EpisodeMatch"},"title":"Matches","type":"array"},"ambiguous":{"default":false,"title":"Ambiguous","type":"boolean"},"simplecast_episode":{"anyOf":[{"$ref":"#/components/schemas/SimplecastEpisodeRef"},{"type":"null"}],"default":null,"description":"The Simplecast episode the id resolved to (title and date come from the show's Simplecast analytics)."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"}},"required":["show_id","computed_at"],"title":"EpisodeLookupResult","type":"object"},"EpisodeMatch":{"properties":{"episode_id":{"description":"The Listener episode id (a Spotify or Apple id) used by every other episode endpoint.","title":"Episode Id","type":"string"},"title":{"title":"Title","type":"string"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"source_platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Source Platform"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"cluster_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Public share page of the episode's cluster.","title":"Cluster Url"},"match":{"$ref":"#/components/schemas/MatchInfo"}},"required":["episode_id","title","match"],"title":"EpisodeMatch","type":"object"},"EpisodeRow":{"description":"One episodes-table row: the episode plus its source cluster's reach.","properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD parsed with the app's date rules; null when the stored date is unreadable.","title":"Published At"},"date_raw":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Date Raw"},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Duration"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Duration Seconds"},"episode_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Number"},"source_platform":{"description":"'spotify' | 'apple' | 'youtube' | 'manual' | 'cluster' | provider key | 'unknown'.","title":"Source Platform","type":"string"},"platform_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform Label"},"is_manual":{"default":false,"title":"Is Manual","type":"boolean"},"is_external":{"default":false,"title":"Is External","type":"boolean"},"is_synthetic":{"default":false,"description":"Row invented by the app for a chart / Apple entry without a stored episode.","title":"Is Synthetic","type":"boolean"},"explicit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Explicit"},"cover":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cover"},"share_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Share Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Truncated in list rows; full text on `GET /v1/shows/{show_id}/episodes/{episode_id}`.","title":"Description"},"tags":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"{series, format, guests}.","title":"Tags","type":"object"},"brands":{"description":"Sponsored-node brands and linked campaign brands on the source cluster.","items":{"type":"string"},"title":"Brands","type":"array"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"has_cluster":{"default":false,"description":"A source cluster exists or any reach / clips / posts > 0 (the page's rule).","title":"Has Cluster","type":"boolean"},"cluster_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Type"},"metrics_source":{"default":"none","title":"Metrics Source","type":"string"},"summary_stale":{"default":false,"title":"Summary Stale","type":"boolean"},"freshness":{"$ref":"#/components/schemas/ClusterFreshness2"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"refresh_error_count":{"default":0,"title":"Refresh Error Count","type":"integer"},"cluster_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Public Url"},"cluster_app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster App Url"},"goals":{"anyOf":[{"$ref":"#/components/schemas/EpisodeGoals"},{"type":"null"}],"default":null},"benchmark":{"anyOf":[{"$ref":"#/components/schemas/EpisodeBenchmark"},{"type":"null"}],"default":null}},"required":["id","title","source_platform","freshness"],"title":"EpisodeRow","type":"object"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","doc_url","request_id"],"properties":{"type":{"type":"string","enum":["api_error","authentication_error","conflict_error","idempotency_error","invalid_request_error","not_found_error","permission_error","rate_limit_error"]},"code":{"type":"string","enum":["body_invalid_json","body_too_large","confirmation_required","credential_expired","credential_invalid","credential_missing","credential_revoked","idempotency_key_in_use","idempotency_key_reused","internal_error","method_not_allowed","oauth_required","parameter_invalid","parameter_missing","parameter_unknown","plan_required","rate_limited","resource_not_found","route_not_found","scope_missing","service_unavailable","upstream_error","version_invalid","workspace_mismatch","writes_disabled"]},"message":{"type":"string","description":"Human-readable; safe to show."},"param":{"type":"string","description":"The parameter at fault, when there is one."},"required_scope":{"type":"string","description":"scope_missing only: the scope the endpoint needs."},"preview":{"description":"confirmation_required only: the exact payload that would be written."},"doc_url":{"type":"string","format":"uri"},"request_id":{"type":"string","pattern":"^req_[A-Za-z0-9]{20}$"}}}},"examples":[{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"Unknown show id: abc123. Valid show ids in this workspace: Uf9fDh5AsUp8Xr0Hi3Jb7GmZf1Gp, Am0QyL5tAd4Dr5Zg2Km8WqOp7Sto.","param":"show_id","doc_url":"https://developers.listener.com/docs/errors","request_id":"req_9m9ReX1wIa7Na0TpP6eG"}}]},"Event":{"type":"object","required":["object","id","type","created","data"],"properties":{"object":{"const":"event"},"id":{"type":"string","description":"evt_…"},"type":{"type":"string","examples":["campaign.updated"]},"api_version":{"type":"string"},"created":{"type":"string","format":"date-time"},"workspace_id":{"type":"string"},"source":{"type":"string","enum":["api","app","system"]},"data":{"type":"object","properties":{"object":{"type":"object"},"previous_attributes":{"type":["object","null"]}}},"request":{"type":["object","null"],"properties":{"id":{"type":["string","null"]},"idempotency_key":{"type":["string","null"]}}}}},"EventType":{"type":"object","required":["object","name"],"properties":{"object":{"const":"event_type"},"name":{"type":"string","description":"The event type, e.g. campaign.updated."},"domain":{"type":"string","description":"The resource family (campaign, cluster, report …)."},"description":{"type":"string"},"sources":{"type":"array","items":{"type":"string","enum":["api","app","system"]}},"wildcard":{"type":"boolean","description":"Delivered to endpoints subscribed to \"*\"."},"example":{"$ref":"#/components/schemas/Event"}}},"ExternalDeliveryListResult":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"campaign_title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Campaign Title"},"rows":{"items":{"$ref":"#/components/schemas/ExternalDeliveryRow"},"title":"Rows","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"row_count":{"default":0,"title":"Row Count","type":"integer"},"totals_by_source":{"additionalProperties":{"$ref":"#/components/schemas/ExternalDeliveryTotals"},"title":"Totals By Source","type":"object"},"note":{"description":"These are counts reported by the ad server; they are never added to Listener reach totals.","title":"Note","type":"string"},"computed_at":{"title":"Computed At","type":"string"}},"required":["campaign_id","page","note","computed_at"],"title":"ExternalDeliveryListResult","type":"object"},"ExternalDeliveryRow":{"properties":{"id":{"description":"'xd_…'","title":"Id","type":"string"},"source":{"enum":["adswizz","audioserve","other"],"title":"Source","type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Label"},"slot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slot Id"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD for a single day; null when the row covers start_date..end_date.","title":"Date"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"End Date"},"impressions":{"title":"Impressions","type":"integer"},"listeners":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Listeners"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created By"}},"required":["id","source","impressions"],"title":"ExternalDeliveryRow","type":"object"},"ExternalDeliveryRowInput":{"additionalProperties":false,"description":"One ad-server delivery figure for a day (`date`) or a period (`start_date` + `end_date`).","properties":{"source":{"description":"Where the count comes from: adswizz, audioserve or other.","enum":["adswizz","audioserve","other"],"type":"string"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Your own label, e.g. the ad server's line item name (≤ 120 characters)."},"slot_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The campaign slot the delivery belongs to (its show is filled in when show_id is omitted)."},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The show that ran the ads."},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD for one day. Send either date or start_date + end_date."},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First day of the period (YYYY-MM-DD)."},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the period (YYYY-MM-DD, inclusive)."},"impressions":{"description":"Impressions the ad server counted.","minimum":0,"type":"integer"},"listeners":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Unique listeners the ad server counted, when it reports them."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Free-text note (≤ 500 characters)."}},"required":["source","impressions"],"type":"object"},"ExternalDeliveryTotals":{"properties":{"rows":{"default":0,"title":"Rows","type":"integer"},"impressions":{"default":0,"title":"Impressions","type":"integer"},"listeners":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Sum of the rows that report listeners; null when none do.","title":"Listeners"}},"title":"ExternalDeliveryTotals","type":"object"},"FindEpisodeContentResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"configured":{"title":"Configured","type":"boolean"},"episode":{"anyOf":[{"$ref":"#/components/schemas/FoundEpisode"},{"type":"null"}],"default":null},"candidates":{"description":"Set when episode_title matched several episodes: pick one and call again with its id.","items":{"$ref":"#/components/schemas/BuildEpisode"},"title":"Candidates","type":"array"},"items":{"items":{"$ref":"#/components/schemas/FoundPost"},"title":"Items","type":"array"},"total":{"default":0,"title":"Total","type":"integer"},"library_count":{"default":0,"title":"Library Count","type":"integer"},"external_count":{"default":0,"title":"External Count","type":"integer"},"sure_count":{"default":0,"title":"Sure Count","type":"integer"},"in_cluster_count":{"default":0,"title":"In Cluster Count","type":"integer"},"searched_handles":{"description":"Extra accounts passed in for this search.","items":{"type":"string"},"title":"Searched Handles","type":"array"},"searched":{"description":"Every account searched, with posts found and any fetch error.","items":{"$ref":"#/components/schemas/SearchedAccount"},"title":"Searched","type":"array"},"window":{"anyOf":[{"$ref":"#/components/schemas/SourceWindow"},{"type":"null"}],"default":null,"description":"Days searched before/after the episode date."},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","configured","computed_at","cache_age_seconds"],"title":"FindEpisodeContentResult","type":"object"},"First30DaysAvailability":{"properties":{"available":{"title":"Available","type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"dated_count":{"default":0,"title":"Dated Count","type":"integer"},"total_count":{"default":0,"title":"Total Count","type":"integer"},"undated_with_metrics_count":{"default":0,"title":"Undated With Metrics Count","type":"integer"}},"required":["available"],"title":"First30DaysAvailability","type":"object"},"First30DaysEstimate":{"properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"availability":{"$ref":"#/components/schemas/First30DaysAvailability"},"as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"As Of"}},"required":["availability"],"title":"First30DaysEstimate","type":"object"},"FoundEpisode":{"properties":{"id":{"title":"Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"}},"required":["id"],"title":"FoundEpisode","type":"object"},"FoundPost":{"properties":{"key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Key"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"library | external.","title":"Source"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Display label (TikTok, YouTube Shorts, X …).","title":"Platform"},"platform_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Internal slug (tiktok, youtube_short, x …).","title":"Platform Key"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Canonical Id"},"matched_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Matched By"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Text"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handle"},"origin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"connected | learned | added | search.","title":"Origin"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"is_short":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Is Short"},"duration_sec":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Duration Sec"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Thumbnail"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/PostMetrics"},{"type":"null"}],"default":null},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"sure | likely | possible (from the judge; possible = less certain, 0.3-0.5); null when not matched to this episode or when judge=false.","title":"Label"},"query_match":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"0-1 share of the `query` words found in the post (only when a query was given).","title":"Query Match"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"in_cluster":{"default":false,"description":"Already a node of this episode's cluster.","title":"In Cluster","type":"boolean"}},"title":"FoundPost","type":"object"},"FreshnessEntry":{"properties":{"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Updated"},"age_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Age Hours"},"stale":{"default":true,"description":"True when older than 36 hours or unknown.","title":"Stale","type":"boolean"}},"title":"FreshnessEntry","type":"object"},"GetAccountDedupViewResult":{"properties":{"platforms_checked":{"items":{"type":"string"},"title":"Platforms Checked","type":"array"},"has_duplicates":{"title":"Has Duplicates","type":"boolean"},"duplicate_platforms":{"items":{"type":"string"},"title":"Duplicate Platforms","type":"array"},"groups":{"items":{"$ref":"#/components/schemas/AccountGroupModel"},"title":"Groups","type":"array"},"duplicate_groups":{"items":{"$ref":"#/components/schemas/AccountGroupModel"},"title":"Duplicate Groups","type":"array"},"suppressed":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"show id → platforms skipped in unique mode.","title":"Suppressed","type":"object"},"applies_to":{"items":{"type":"string"},"title":"Applies To","type":"array"},"never_applied_to":{"items":{"type":"string"},"title":"Never Applied To","type":"array"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["platforms_checked","has_duplicates","duplicate_platforms","groups","duplicate_groups","applies_to","never_applied_to","show_ids","computed_at"],"title":"GetAccountDedupViewResult","type":"object"},"GetBrandResult":{"properties":{"slug":{"title":"Slug","type":"string"},"name":{"title":"Name","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Logo"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Notes"},"has_contact":{"default":false,"title":"Has Contact","type":"boolean"},"has_brand_doc":{"default":false,"title":"Has Brand Doc","type":"boolean"},"brand_doc":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The canonical campaignBrands doc (contact fields removed).","title":"Brand Doc"},"invites":{"description":"brandInvites for this brand (emails masked).","items":{"additionalProperties":true,"type":"object"},"title":"Invites","type":"array"},"campaign_ids":{"items":{"type":"string"},"title":"Campaign Ids","type":"array"},"campaign_count":{"default":0,"title":"Campaign Count","type":"integer"},"totals":{"additionalProperties":true,"title":"Totals","type":"object"},"campaign_rows":{"items":{"additionalProperties":true,"type":"object"},"title":"Campaign Rows","type":"array"},"show_performance":{"items":{"additionalProperties":true,"type":"object"},"title":"Show Performance","type":"array"},"shows":{"items":{"additionalProperties":true,"type":"object"},"title":"Shows","type":"array"},"emv_total":{"default":0,"title":"Emv Total","type":"number"},"emv_by_campaign":{"additionalProperties":{"type":"number"},"title":"Emv By Campaign","type":"object"},"trend":{"additionalProperties":true,"description":"{time_range, chart_type, points: [...]} from brand_trend_series.","title":"Trend","type":"object"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["slug","name","totals","campaign_rows","show_performance","shows","trend","precision","app_url","computed_at","cache_age_seconds"],"title":"GetBrandResult","type":"object"},"GetCampaignCpmInsightsResult":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"title":{"title":"Title","type":"string"},"expected_cpm":{"default":0,"title":"Expected Cpm","type":"number"},"delivered_cpm":{"default":0,"title":"Delivered Cpm","type":"number"},"delivered_cpm_status":{"default":"pending","title":"Delivered Cpm Status","type":"string"},"delivered_cpm_detail":{"additionalProperties":true,"title":"Delivered Cpm Detail","type":"object"},"format_cpm":{"additionalProperties":true,"title":"Format Cpm","type":"object"},"benchmarks":{"additionalProperties":{"$ref":"#/components/schemas/CpmBenchmark"},"description":"long_form / short_form delivered CPM vs the median of the 12 most recent peers with a CPM.","title":"Benchmarks","type":"object"},"peers":{"items":{"$ref":"#/components/schemas/CpmPeerRow"},"title":"Peers","type":"array"},"peers_considered":{"default":0,"title":"Peers Considered","type":"integer"},"peers_with_cpm":{"additionalProperties":{"type":"integer"},"title":"Peers With Cpm","type":"object"},"workspace_campaign_count":{"default":0,"title":"Workspace Campaign Count","type":"integer"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["campaign_id","title","precision","computed_at","cache_age_seconds"],"title":"GetCampaignCpmInsightsResult","type":"object"},"GetCampaignResult":{"properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"status":{"enum":["upcoming","active","completed"],"title":"Status","type":"string"},"status_label":{"title":"Status Label","type":"string"},"status_is_manual":{"default":false,"title":"Status Is Manual","type":"boolean"},"status_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status Updated At"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"End Date"},"start_is_fallback":{"default":false,"title":"Start Is Fallback","type":"boolean"},"days_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Days Remaining"},"days_until_start":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Days Until Start"},"timing":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Timing"},"brand":{"$ref":"#/components/schemas/CampaignBrandRef"},"goals":{"$ref":"#/components/schemas/CampaignGoals"},"has_goal":{"default":false,"title":"Has Goal","type":"boolean"},"goal_progress_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Goal Progress Pct"},"goal_progress_clamped_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Goal Progress Clamped Pct"},"pacing":{"$ref":"#/components/schemas/CampaignPacing"},"budget":{"default":0,"title":"Budget","type":"number"},"slot_budget_total":{"default":0,"title":"Slot Budget Total","type":"number"},"expected_impressions":{"default":0,"title":"Expected Impressions","type":"number"},"expected_cpm":{"default":0,"title":"Expected Cpm","type":"number"},"delivered_cpm":{"default":0,"title":"Delivered Cpm","type":"number"},"delivered_cpm_status":{"default":"pending","title":"Delivered Cpm Status","type":"string"},"delivered_cpm_detail":{"additionalProperties":true,"title":"Delivered Cpm Detail","type":"object"},"format_cpm":{"additionalProperties":true,"title":"Format Cpm","type":"object"},"emv":{"additionalProperties":true,"description":"EMV block incl. resolved settings + settings_source.","title":"Emv","type":"object"},"reach":{"$ref":"#/components/schemas/CampaignReach"},"engagement":{"default":0,"title":"Engagement","type":"number"},"engagement_rate":{"default":0,"title":"Engagement Rate","type":"number"},"first_30_days":{"additionalProperties":true,"title":"First 30 Days","type":"object"},"linked_show_ids":{"items":{"type":"string"},"title":"Linked Show Ids","type":"array"},"linked_show_names":{"items":{"type":"string"},"title":"Linked Show Names","type":"array"},"show_count":{"default":0,"title":"Show Count","type":"integer"},"cluster_ids":{"items":{"type":"string"},"title":"Cluster Ids","type":"array"},"clusters_loaded":{"default":0,"title":"Clusters Loaded","type":"integer"},"clusters_missing":{"items":{"type":"string"},"title":"Clusters Missing","type":"array"},"total_slots":{"default":0,"title":"Total Slots","type":"integer"},"linked_slots":{"default":0,"title":"Linked Slots","type":"integer"},"unlinked_slot_count":{"default":0,"title":"Unlinked Slot Count","type":"integer"},"live_slots":{"default":0,"title":"Live Slots","type":"integer"},"slots":{"items":{"$ref":"#/components/schemas/CampaignSlot"},"title":"Slots","type":"array"},"show_breakdown":{"items":{"$ref":"#/components/schemas/CampaignShowBreakdown"},"title":"Show Breakdown","type":"array"},"air_checks":{"additionalProperties":true,"title":"Air Checks","type":"object"},"excluded_node_count":{"default":0,"title":"Excluded Node Count","type":"integer"},"excluded_node_ids_count":{"default":0,"title":"Excluded Node Ids Count","type":"integer"},"featured_content_node_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Featured Content Node Id"},"merged_from":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"default":null,"title":"Merged From"},"copied_from":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Copied From"},"created_via":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created Via"},"duplicate":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Duplicate"},"share":{"additionalProperties":true,"title":"Share","type":"object"},"activity_log":{"$ref":"#/components/schemas/ActivityLog"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["id","title","status","status_label","brand","goals","pacing","reach","activity_log","app_url","precision","computed_at","cache_age_seconds"],"title":"GetCampaignResult","type":"object"},"GetCampaignTimelineResult":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"title":{"title":"Title","type":"string"},"window":{"additionalProperties":true,"description":"{time_range, chart_type, start, end, previous_start, previous_end} as the chart resolves it.","title":"Window","type":"object"},"chart_type":{"enum":["daily","cumulative"],"title":"Chart Type","type":"string"},"totals":{"additionalProperties":{"type":"number"},"title":"Totals","type":"object"},"growth":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":"vs the equal-length previous window; None for all-time.","title":"Growth","type":"object"},"reach_series":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"title":"Reach Series","type":"array"},"audio_series":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"title":"Audio Series","type":"array"},"youtube_series":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"title":"Youtube Series","type":"array"},"social_series":{"items":{"$ref":"#/components/schemas/SeriesPoint"},"title":"Social Series","type":"array"},"events_counted":{"title":"Events Counted","type":"integer"},"emv_series":{"items":{"$ref":"#/components/schemas/EmvSeriesPoint"},"title":"Emv Series","type":"array"},"emv_total":{"title":"Emv Total","type":"number"},"emv_by_platform":{"additionalProperties":{"type":"number"},"title":"Emv By Platform","type":"object"},"emv_enabled":{"default":false,"title":"Emv Enabled","type":"boolean"},"emv_nodes_counted":{"default":0,"title":"Emv Nodes Counted","type":"integer"},"emv_points_thinned":{"default":false,"description":"True when the EMV series was thinned to ≤ 180 points by summing whole weeks.","title":"Emv Points Thinned","type":"boolean"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["campaign_id","title","window","chart_type","totals","growth","reach_series","audio_series","youtube_series","social_series","events_counted","emv_series","emv_total","precision","computed_at","cache_age_seconds"],"title":"GetCampaignTimelineResult","type":"object"},"GetClusterReportResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"include_merged":{"default":false,"title":"Include Merged","type":"boolean"},"network":{"$ref":"#/components/schemas/ClusterReportBlock"},"shows":{"items":{"$ref":"#/components/schemas/ClusterReportShowBlock"},"title":"Shows","type":"array"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"categories":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"title":"Categories"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"summary_stale_count":{"default":0,"description":"Cluster rows whose stored summary could not be verified and were not recomputed.","title":"Summary Stale Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["window","network","shows","show_ids","coverage","computed_at","cache_age_seconds"],"title":"GetClusterReportResult","type":"object"},"GetClusterResult":{"properties":{"cluster":{"$ref":"#/components/schemas/ClusterMeta"},"metrics":{"$ref":"#/components/schemas/ClusterMetrics"},"metrics_source":{"title":"Metrics Source","type":"string"},"first_30_days":{"$ref":"#/components/schemas/First30DaysEstimate"},"emv":{"$ref":"#/components/schemas/ClusterEmvEstimate"},"node_count":{"description":"Content nodes (episode / clip / post) on the document.","title":"Node Count","type":"integer"},"nodes":{"items":{"$ref":"#/components/schemas/ClusterNode"},"title":"Nodes","type":"array"},"nodes_truncated":{"default":false,"title":"Nodes Truncated","type":"boolean"},"nodes_returned":{"default":0,"title":"Nodes Returned","type":"integer"},"tag_rollups":{"$ref":"#/components/schemas/TagRollups"},"subclusters":{"$ref":"#/components/schemas/SubclusterRollups"},"edges":{"description":"Every canvas edge between content nodes, never truncated by node_limit, so parent links resolve even for nodes not returned.","items":{"$ref":"#/components/schemas/ClusterEdge"},"title":"Edges","type":"array"},"sponsor_brands":{"items":{"type":"string"},"title":"Sponsor Brands","type":"array"},"brands":{"items":{"type":"string"},"title":"Brands","type":"array"},"linked_campaigns":{"items":{"$ref":"#/components/schemas/LinkedCampaignRef"},"title":"Linked Campaigns","type":"array"},"freshness":{"$ref":"#/components/schemas/ClusterFreshness2"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"last_refresh_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refresh Attempt At"},"last_refresh_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refresh Source"},"refresh_errors":{"items":{"$ref":"#/components/schemas/RefreshError"},"title":"Refresh Errors","type":"array"},"refresh_error_count":{"default":0,"title":"Refresh Error Count","type":"integer"},"platform_freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Platform Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["cluster","metrics","metrics_source","first_30_days","emv","node_count","tag_rollups","subclusters","freshness","computed_at","cache_age_seconds"],"title":"GetClusterResult","type":"object"},"GetClusterTimelineResult":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"cluster_id":{"title":"Cluster Id","type":"string"},"title":{"title":"Title","type":"string"},"granularity":{"enum":["daily","weekly","monthly"],"title":"Granularity","type":"string"},"chart_type":{"enum":["daily","cumulative"],"title":"Chart Type","type":"string"},"synthetic":{"description":"True: the app's shape-only curve (lifetime totals spread over time), not measured data.","title":"Synthetic","type":"boolean"},"start_date":{"title":"Start Date","type":"string"},"start_date_from_episode":{"title":"Start Date From Episode","type":"boolean"},"total_days":{"title":"Total Days","type":"integer"},"data_points":{"title":"Data Points","type":"integer"},"total_views":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Total Views"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Total Engagement"},"points":{"items":{"$ref":"#/components/schemas/TimelinePoint"},"title":"Points","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show","cluster_id","title","granularity","chart_type","synthetic","start_date","start_date_from_episode","total_days","data_points","total_views","total_engagement","points","computed_at","cache_age_seconds"],"title":"GetClusterTimelineResult","type":"object"},"GetDashboardKpisResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"time_range":{"title":"Time Range","type":"string"},"table_mode":{"enum":["reach","audience","demographics"],"title":"Table Mode","type":"string"},"tiles":{"items":{"$ref":"#/components/schemas/KpiTile"},"title":"Tiles","type":"array"},"emv":{"$ref":"#/components/schemas/EmvBreakdown"},"per_platform_reach":{"additionalProperties":{"type":"integer"},"title":"Per Platform Reach","type":"object"},"shows":{"items":{"$ref":"#/components/schemas/DashboardShowRow"},"title":"Shows","type":"array"},"top_content":{"additionalProperties":{"items":{"$ref":"#/components/schemas/TopContentItem"},"type":"array"},"description":"platform → top 3 items in the window by plays/views/impressions (last 30 days on a 90d window).","title":"Top Content","type":"object"},"metric_windows":{"additionalProperties":{"type":"string"},"description":"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.","title":"Metric Windows","type":"object"}},"required":["window","coverage","computed_at","time_range","table_mode","tiles","emv","shows"],"title":"GetDashboardKpisResult","type":"object"},"GetEpisodeResult":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"episode":{"$ref":"#/components/schemas/EpisodeRow"},"sources":{"description":"Index sources that produced the row (stored feed, chart, apple, cluster, provider).","items":{"type":"string"},"title":"Sources","type":"array"},"spotify":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Spotify chart / stored stats for the episode when present.","title":"Spotify"},"apple":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Apple"},"youtube":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Youtube"},"cluster":{"anyOf":[{"$ref":"#/components/schemas/EpisodeClusterSummary"},{"type":"null"}],"default":null},"goals":{"anyOf":[{"$ref":"#/components/schemas/GoalsSummary"},{"type":"null"}],"default":null},"benchmark":{"anyOf":[{"$ref":"#/components/schemas/BenchmarkSummary"},{"type":"null"}],"default":null},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show","episode","computed_at","cache_age_seconds"],"title":"GetEpisodeResult","type":"object"},"GetEpisodeTranscriptResult":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"episode_id":{"title":"Episode Id","type":"string"},"title":{"title":"Title","type":"string"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"status":{"enum":["description-fallback","missing"],"title":"Status","type":"string"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Description text (there is no stored transcript); capped at 9,000 characters.","title":"Text"},"truncated":{"default":false,"title":"Truncated","type":"boolean"},"character_count":{"default":0,"title":"Character Count","type":"integer"},"aircheck_excerpts":{"description":"Transcript text found on linked campaigns' air-check analyses, when any.","items":{"$ref":"#/components/schemas/AircheckExcerpt"},"title":"Aircheck Excerpts","type":"array"},"share_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Share Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show","episode_id","title","status","computed_at","cache_age_seconds"],"title":"GetEpisodeTranscriptResult","type":"object"},"GetHostsRankingResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"sort_by":{"enum":["audience","youtube","social","shows_reach","name"],"title":"Sort By","type":"string"},"rows":{"items":{"$ref":"#/components/schemas/HostRow"},"title":"Rows","type":"array"},"total_hosts":{"title":"Total Hosts","type":"integer"},"total_audience":{"title":"Total Audience","type":"integer"},"youtube_audience":{"title":"Youtube Audience","type":"integer"},"social_audience":{"title":"Social Audience","type":"integer"}},"required":["window","coverage","computed_at","sort_by","rows","total_hosts","total_audience","youtube_audience","social_audience"],"title":"GetHostsRankingResult","type":"object"},"GetNetworkOpportunitiesResult":{"properties":{"opportunities":{"items":{"$ref":"#/components/schemas/NetworkOpportunity"},"title":"Opportunities","type":"array"},"total_pairs_considered":{"title":"Total Pairs Considered","type":"integer"},"reach_aware":{"description":"True when combined_reach / score used cluster reach.","title":"Reach Aware","type":"boolean"},"reach_source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"'cluster_summaries' when reach was loaded.","title":"Reach Source"},"show_count":{"title":"Show Count","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["opportunities","total_pairs_considered","reach_aware","show_count","computed_at","cache_age_seconds"],"title":"GetNetworkOpportunitiesResult","type":"object"},"GetPlanResult":{"properties":{"plan":{"title":"Plan","type":"string"},"plan_source":{"enum":["explicit","subscription","is_network","agency_managed","default_free"],"title":"Plan Source","type":"string"},"is_paid":{"title":"Is Paid","type":"boolean"},"premium_platforms":{"description":"Platforms the app marks isPremium (locked on the free plan).","items":{"type":"string"},"title":"Premium Platforms","type":"array"},"locked_platforms":{"description":"Premium platforms this plan cannot connect.","items":{"type":"string"},"title":"Locked Platforms","type":"array"},"gated_features":{"additionalProperties":{"type":"boolean"},"description":"feature → available on this plan.","title":"Gated Features","type":"object"},"shows_plans":{"additionalProperties":{"type":"string"},"description":"show_id → resolved plan for each managed show.","title":"Shows Plans","type":"object"},"writes_enabled":{"title":"Writes Enabled","type":"boolean"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"}},"required":["plan","plan_source","is_paid","premium_platforms","locked_platforms","gated_features","writes_enabled","computed_at","cache_age_seconds"],"title":"GetPlanResult","type":"object"},"GetPlatformDistributionResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"enum":["views","followers","engagement"],"title":"Metric","type":"string"},"social_count_mode":{"default":"all","enum":["all","unique"],"title":"Social Count Mode","type":"string"},"entries":{"items":{"$ref":"#/components/schemas/DistributionEntry"},"title":"Entries","type":"array"},"total":{"title":"Total","type":"integer"},"source":{"description":"Where the values come from: daily performance (views/engagement) or live follower counts (followers).","title":"Source","type":"string"}},"required":["window","coverage","computed_at","metric","entries","total","source"],"title":"GetPlatformDistributionResult","type":"object"},"GetPlatformStatsResult":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"time_range":{"enum":["7d","30d","90d"],"title":"Time Range","type":"string"},"window":{"$ref":"#/components/schemas/WindowInfo"},"metric_windows":{"additionalProperties":{"type":"string"},"description":"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.","title":"Metric Windows","type":"object"},"platforms":{"items":{"$ref":"#/components/schemas/PlatformStatsBlock"},"title":"Platforms","type":"array"},"requested_platform":{"title":"Requested Platform","type":"string"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show","time_range","window","platforms","requested_platform","computed_at"],"title":"GetPlatformStatsResult","type":"object"},"GetPublicUrlsResult":{"properties":{"entity":{"enum":["network","show","cluster","campaign","brand","report","chart","link"],"title":"Entity","type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App Url"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["entity"],"title":"GetPublicUrlsResult","type":"object"},"GetReachSummaryResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"default":"reach","enum":["reach","engagement"],"title":"Metric","type":"string"},"social_count_mode":{"default":"all","enum":["all","unique"],"title":"Social Count Mode","type":"string"},"total":{"$ref":"#/components/schemas/ReachCategory"},"youtube":{"$ref":"#/components/schemas/ReachCategory"},"audio":{"$ref":"#/components/schemas/ReachCategory"},"social":{"$ref":"#/components/schemas/ReachCategory"},"newsletter":{"$ref":"#/components/schemas/ReachCategory","description":"Beehiiv + Substack newsletter opens; part of total on the analytics page."},"per_platform":{"additionalProperties":{"type":"integer"},"title":"Per Platform","type":"object"},"previous_per_platform":{"additionalProperties":{"type":"integer"},"title":"Previous Per Platform","type":"object"},"suppressed_platforms_by_show":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Unique mode only: show → platforms skipped because another show is canonical for the same account.","title":"Suppressed Platforms By Show","type":"object"},"shows_in_totals":{"default":0,"title":"Shows In Totals","type":"integer"}},"required":["window","coverage","computed_at","total","youtube","audio","social","newsletter"],"title":"GetReachSummaryResult","type":"object"},"GetReachTimelineResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"enum":["reach","engagement"],"title":"Metric","type":"string"},"chart_type":{"enum":["daily","cumulative"],"title":"Chart Type","type":"string"},"social_count_mode":{"default":"all","enum":["all","unique"],"title":"Social Count Mode","type":"string"},"rows":{"items":{"$ref":"#/components/schemas/TimelineRow"},"title":"Rows","type":"array"},"previous_rows":{"anyOf":[{"items":{"$ref":"#/components/schemas/TimelineRow"},"type":"array"},{"type":"null"}],"default":null,"title":"Previous Rows"},"total":{"title":"Total","type":"integer"},"previous_total":{"title":"Previous Total","type":"integer"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Growth"},"per_platform":{"additionalProperties":{"type":"integer"},"title":"Per Platform","type":"object"},"previous_per_platform":{"additionalProperties":{"type":"integer"},"title":"Previous Per Platform","type":"object"},"peak_day":{"anyOf":[{"$ref":"#/components/schemas/TimelineRow"},{"type":"null"}],"default":null},"per_show":{"anyOf":[{"additionalProperties":{"items":{"$ref":"#/components/schemas/ShowSeriesRow"},"type":"array"},"type":"object"},{"type":"null"}],"default":null,"description":"show id → daily totals (include_per_show=True).","title":"Per Show"}},"required":["window","coverage","computed_at","metric","chart_type","rows","total","previous_total"],"title":"GetReachTimelineResult","type":"object"},"GetRecentPostsResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"group_by":{"enum":["none","day","platform"],"title":"Group By","type":"string"},"platforms":{"items":{"type":"string"},"title":"Platforms","type":"array"},"posts":{"anyOf":[{"items":{"$ref":"#/components/schemas/PostRecord"},"type":"array"},{"type":"null"}],"default":null,"description":"Flat newest-first list (group_by='none').","title":"Posts"},"groups":{"anyOf":[{"items":{"$ref":"#/components/schemas/PostGroup"},"type":"array"},{"type":"null"}],"default":null,"title":"Groups"},"page":{"$ref":"#/components/schemas/PageInfo"},"posts_by_platform":{"additionalProperties":{"type":"integer"},"description":"Counts before limit/offset.","title":"Posts By Platform","type":"object"}},"required":["window","coverage","computed_at","group_by","platforms","page"],"title":"GetRecentPostsResult","type":"object"},"GetRefreshStatusResult":{"properties":{"shows":{"items":{"$ref":"#/components/schemas/ShowRefreshStatus"},"title":"Shows","type":"array"},"stale_platforms":{"description":"Platforms stale on at least one show.","items":{"type":"string"},"title":"Stale Platforms","type":"array"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"pending_request_count":{"default":0,"title":"Pending Request Count","type":"integer"},"shows_with_stale_clusters":{"default":0,"title":"Shows With Stale Clusters","type":"integer"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["shows","show_ids","computed_at"],"title":"GetRefreshStatusResult","type":"object"},"GetReportResult":{"properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"network_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Network Name"},"time_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Range"},"comparison_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Comparison Mode"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created By"},"created_via":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created Via"},"is_automated":{"default":false,"title":"Is Automated","type":"boolean"},"is_test":{"default":false,"title":"Is Test","type":"boolean"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Template Id"},"element_count":{"default":0,"title":"Element Count","type":"integer"},"element_ids":{"items":{"type":"string"},"title":"Element Ids","type":"array"},"element_metrics":{"items":{"type":"string"},"title":"Element Metrics","type":"array"},"element_types":{"additionalProperties":{"type":"integer"},"title":"Element Types","type":"object"},"report_scope":{"anyOf":[{"$ref":"#/components/schemas/ReportScope"},{"type":"null"}],"default":null},"headline":{"$ref":"#/components/schemas/ReportHeadline"},"has_data":{"default":false,"title":"Has Data","type":"boolean"},"urls":{"$ref":"#/components/schemas/ReportUrls"},"elements":{"items":{"$ref":"#/components/schemas/ReportElement"},"title":"Elements","type":"array"},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The stored data snapshot (arrays truncated to 200 items when data_truncated).","title":"Data"},"data_keys":{"items":{"type":"string"},"title":"Data Keys","type":"array"},"data_truncated":{"default":false,"title":"Data Truncated","type":"boolean"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["id","title","headline","urls","computed_at","cache_age_seconds"],"title":"GetReportResult","type":"object"},"GetShowResult":{"properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"handle":{"default":"","title":"Handle","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"description":{"default":"","title":"Description","type":"string"},"author":{"default":"","title":"Author","type":"string"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"hidden_categories":{"items":{"type":"string"},"title":"Hidden Categories","type":"array"},"main_platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Main Platform"},"plan":{"title":"Plan","type":"string"},"agency_managed":{"default":false,"title":"Agency Managed","type":"boolean"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created By"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"hosts":{"items":{"$ref":"#/components/schemas/HostInfo"},"title":"Hosts","type":"array"},"show_host_section":{"default":false,"title":"Show Host Section","type":"boolean"},"talent":{"items":{"$ref":"#/components/schemas/TalentMember"},"title":"Talent","type":"array"},"podcast_metadata":{"$ref":"#/components/schemas/PodcastMetadata"},"spotify_rating":{"anyOf":[{"$ref":"#/components/schemas/SpotifyRating"},{"type":"null"}],"default":null},"platforms":{"items":{"$ref":"#/components/schemas/PlatformState"},"title":"Platforms","type":"array"},"connected_platforms":{"items":{"type":"string"},"title":"Connected Platforms","type":"array"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"sponsorship_packages":{"items":{"additionalProperties":true,"type":"object"},"title":"Sponsorship Packages","type":"array"},"collaborations":{"items":{"$ref":"#/components/schemas/Collaboration"},"title":"Collaborations","type":"array"},"past_guests":{"items":{"$ref":"#/components/schemas/PastGuest"},"title":"Past Guests","type":"array"},"survey_data":{"anyOf":[{"$ref":"#/components/schemas/SurveyData"},{"type":"null"}],"default":null},"last_cluster_update":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Cluster Update"},"last_update_stats":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Last Update Stats"},"episode_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Episode Count"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"}},"required":["id","name","plan","podcast_metadata","app_url","computed_at","cache_age_seconds"],"title":"GetShowResult","type":"object"},"GetShowsRankingResult":{"properties":{"window":{"$ref":"#/components/schemas/WindowInfo"},"coverage":{"$ref":"#/components/schemas/CoverageInfo"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across the scoped shows.","title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"show_ids":{"description":"Shows included after show_ids/categories filtering.","items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"metric":{"default":"reach","enum":["reach","engagement"],"title":"Metric","type":"string"},"sort_by":{"enum":["total","youtube","audio","social","growth"],"title":"Sort By","type":"string"},"rows":{"items":{"$ref":"#/components/schemas/ShowRankingRow"},"title":"Rows","type":"array"},"total":{"description":"Sum of the rows' totals (never deduped, so it can exceed `GET /v1/analytics/reach` in unique mode).","title":"Total","type":"integer"}},"required":["window","coverage","computed_at","sort_by","rows","total"],"title":"GetShowsRankingResult","type":"object"},"GetTeamResult":{"properties":{"owner_uid":{"title":"Owner Uid","type":"string"},"members":{"items":{"$ref":"#/components/schemas/TeamMember"},"title":"Members","type":"array"},"pending_invites":{"items":{"$ref":"#/components/schemas/TeamMember"},"title":"Pending Invites","type":"array"},"team_size":{"description":"Owner + accepted members.","title":"Team Size","type":"integer"},"talent_by_show":{"items":{"$ref":"#/components/schemas/ShowTalent"},"title":"Talent By Show","type":"array"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"}},"required":["owner_uid","members","pending_invites","team_size","computed_at","cache_age_seconds"],"title":"GetTeamResult","type":"object"},"GetWorkspaceLibraryFileResult":{"properties":{"id":{"title":"Id","type":"string"},"filename":{"title":"Filename","type":"string"},"media_type":{"default":"application/octet-stream","title":"Media Type","type":"string"},"size_bytes":{"default":0,"title":"Size Bytes","type":"integer"},"detected_kind":{"default":"unknown","title":"Detected Kind","type":"string"},"is_text_like":{"default":false,"title":"Is Text Like","type":"boolean"},"parse_status":{"default":"unknown","title":"Parse Status","type":"string"},"parse_warnings":{"items":{"type":"string"},"title":"Parse Warnings","type":"array"},"status":{"default":"ready","title":"Status","type":"string"},"uploaded_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uploaded At"},"uploaded_by_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uploaded By Uid"},"has_extracted_text":{"default":false,"title":"Has Extracted Text","type":"boolean"},"extracted_text_chars":{"default":0,"description":"Length of the stored extracted text (before the 12,000-character cap).","title":"Extracted Text Chars","type":"integer"},"has_structured_summary":{"default":false,"title":"Has Structured Summary","type":"boolean"},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First ~280 characters of the stored preview text.","title":"Preview"},"extracted_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Stored extracted text, capped at 12,000 characters.","title":"Extracted Text"},"extracted_text_truncated":{"default":false,"title":"Extracted Text Truncated","type":"boolean"},"structured_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Structured Summary"},"storage_path":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Storage Path"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Signed GET URL (1 h) when the Storage bucket is configured.","title":"Download Url"},"download_url_expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Download Url Expires At"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["id","filename","computed_at","cache_age_seconds"],"title":"GetWorkspaceLibraryFileResult","type":"object"},"GetWorkspaceResult":{"properties":{"effective_uid":{"title":"Effective Uid","type":"string"},"authenticated_uid":{"title":"Authenticated Uid","type":"string"},"auth_kind":{"title":"Auth Kind","type":"string"},"key_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Key Label"},"scopes":{"items":{"type":"string"},"title":"Scopes","type":"array"},"kind":{"enum":["network","subnetwork","solo"],"title":"Kind","type":"string"},"is_network":{"title":"Is Network","type":"boolean"},"is_subnetwork":{"title":"Is Subnetwork","type":"boolean"},"parent_network_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Network Uid"},"network_name":{"title":"Network Name","type":"string"},"network_handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Network Handle"},"network_logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Network Logo"},"plan":{"title":"Plan","type":"string"},"shows":{"items":{"$ref":"#/components/schemas/ShowSummary"},"title":"Shows","type":"array"},"show_count":{"title":"Show Count","type":"integer"},"missing_show_ids":{"description":"managedKits entries with no users/ doc; excluded from shows.","items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"team_size":{"title":"Team Size","type":"integer"},"subnetwork_count":{"title":"Subnetwork Count","type":"integer"},"campaign_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Campaign Count"},"integrations_summary":{"additionalProperties":{"type":"integer"},"description":"platform → number of shows with that platform connected or holding data.","title":"Integrations Summary","type":"object"},"data_freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"description":"platform → oldest freshness across shows.","title":"Data Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"network_default_emv":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Network Default Emv"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"app_url":{"title":"App Url","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["effective_uid","authenticated_uid","auth_kind","scopes","kind","is_network","is_subnetwork","network_name","plan","shows","show_count","team_size","subnetwork_count","app_url","computed_at","cache_age_seconds"],"title":"GetWorkspaceResult","type":"object"},"GoalDeltas":{"description":"Percent vs target ((value − target) / target × 100); null without a target.","properties":{"total_reach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Total Reach"},"long_form_reach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Short Form Reach"}},"title":"GoalDeltas","type":"object"},"GoalTargets":{"properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Short Form Reach"}},"title":"GoalTargets","type":"object"},"GoalTargets2":{"additionalProperties":false,"description":"Reach targets; accept ints or shorthand strings like \"250k\", \"1.2M\", \"1,200,000\".","properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"default":null},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"default":null},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"string"},{"type":"null"}],"default":null}},"type":"object"},"GoalsSummary":{"properties":{"targets":{"$ref":"#/components/schemas/GoalTargets"},"sources":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":"Per target: 'series' (override) | 'default' | null.","title":"Sources","type":"object"},"series":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Series"},"has_series_overrides":{"default":false,"title":"Has Series Overrides","type":"boolean"},"has_any":{"default":false,"title":"Has Any","type":"boolean"},"comparable_count":{"default":0,"title":"Comparable Count","type":"integer"}},"required":["targets"],"title":"GoalsSummary","type":"object"},"HeadToHead":{"properties":{"metric":{"title":"Metric","type":"string"},"a":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"A"},"b":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"B"},"delta_a_minus_b":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Delta A Minus B"},"winner":{"anyOf":[{"enum":["a","b","tie"],"type":"string"},{"type":"null"}],"default":null,"title":"Winner"}},"required":["metric"],"title":"HeadToHead","type":"object"},"HostInfo":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"title":"Name","type":"string"},"bio":{"default":"","title":"Bio","type":"string"},"photo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Photo"},"social_links":{"additionalProperties":{"type":"string"},"title":"Social Links","type":"object"}},"required":["name"],"title":"HostInfo","type":"object"},"HostRow":{"properties":{"rank":{"title":"Rank","type":"integer"},"name":{"title":"Name","type":"string"},"bio":{"default":"","title":"Bio","type":"string"},"photo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Photo"},"primary_link":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Primary Link"},"social_links":{"additionalProperties":{"type":"string"},"title":"Social Links","type":"object"},"audience_by_platform":{"additionalProperties":{"type":"integer"},"description":"Host's own per-platform audience (hostInfo.hosts[].socialStats), merged across shows (first non-zero wins, never summed).","title":"Audience By Platform","type":"object"},"total_audience":{"title":"Total Audience","type":"integer"},"youtube_audience":{"title":"Youtube Audience","type":"integer"},"social_audience":{"title":"Social Audience","type":"integer"},"shows":{"items":{"$ref":"#/components/schemas/ShowRef"},"title":"Shows","type":"array"},"shows_reach":{"description":"Sum of the reach of the shows this host appears on in the window (each show counted once).","title":"Shows Reach","type":"integer"}},"required":["rank","name","total_audience","youtube_audience","social_audience","shows","shows_reach"],"title":"HostRow","type":"object"},"InsertionOrderSource":{"properties":{"kind":{"enum":["upload","library","url","base64"],"title":"Kind","type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The upload / library file id, or the URL for kind='url'.","title":"Id"},"file_name":{"title":"File Name","type":"string"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Known for bytes the MCP handled itself; None when the app read Storage directly.","title":"Size Bytes"},"storage_path":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Where the PDF lives in Firebase Storage (the app stores URL/base64 sources under campaign-io/).","title":"Storage Path"}},"required":["kind","file_name"],"title":"InsertionOrderSource","type":"object"},"IntegrationRow":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"platform":{"title":"Platform","type":"string"},"label":{"title":"Label","type":"string"},"group":{"enum":["audio","content"],"title":"Group","type":"string"},"state":{"enum":["connected","pending","disconnected"],"title":"State","type":"string"},"state_reason":{"default":"","description":"Which rule of resolveIntegrationConnectionState fired.","title":"State Reason","type":"string"},"connected_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"Raw `<platform>.connected` on the show doc.","title":"Connected Flag"},"platform_order_connected":{"default":false,"title":"Platform Order Connected","type":"boolean"},"has_data":{"default":false,"title":"Has Data","type":"boolean"},"importing_state":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Importing State"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"setup_step":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Setup Step"},"disconnected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Disconnected At"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Updated"},"age_hours":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Age Hours"},"stale":{"default":true,"title":"Stale","type":"boolean"},"refresh_kind":{"enum":["server","manual_request","none"],"title":"Refresh Kind","type":"string"},"requires_confirm":{"default":false,"title":"Requires Confirm","type":"boolean"},"premium":{"default":false,"title":"Premium","type":"boolean"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Error"}},"required":["show","platform","label","group","state","refresh_kind"],"title":"IntegrationRow","type":"object"},"IntegrationsSummary":{"properties":{"rows":{"title":"Rows","type":"integer"},"connected":{"title":"Connected","type":"integer"},"pending":{"title":"Pending","type":"integer"},"disconnected":{"title":"Disconnected","type":"integer"},"stale_connected":{"description":"Connected rows whose data is older than 36 h (or undated).","title":"Stale Connected","type":"integer"},"by_platform":{"additionalProperties":{"additionalProperties":{"type":"integer"},"type":"object"},"description":"platform → {connected, pending, disconnected, stale}.","title":"By Platform","type":"object"},"shows_with_any_connection":{"title":"Shows With Any Connection","type":"integer"},"shows_without_connections":{"title":"Shows Without Connections","type":"integer"}},"required":["rows","connected","pending","disconnected","stale_connected","shows_with_any_connection","shows_without_connections"],"title":"IntegrationsSummary","type":"object"},"KpiTile":{"properties":{"key":{"title":"Key","type":"string"},"label":{"title":"Label","type":"string"},"value":{"title":"Value","type":"number"},"previous":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Previous"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Growth"},"unit":{"default":"count","enum":["count","percent","usd"],"title":"Unit","type":"string"},"source":{"default":"","title":"Source","type":"string"},"window":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Window this tile's value covers ('90d', '30d', 'live', 'mixed', or a date range). On 90d, likes/comments/posts are last-30-days only.","title":"Window"}},"required":["key","label","value"],"title":"KpiTile","type":"object"},"LibraryFile":{"properties":{"id":{"title":"Id","type":"string"},"filename":{"title":"Filename","type":"string"},"media_type":{"default":"application/octet-stream","title":"Media Type","type":"string"},"size_bytes":{"default":0,"title":"Size Bytes","type":"integer"},"detected_kind":{"default":"unknown","title":"Detected Kind","type":"string"},"is_text_like":{"default":false,"title":"Is Text Like","type":"boolean"},"parse_status":{"default":"unknown","title":"Parse Status","type":"string"},"parse_warnings":{"items":{"type":"string"},"title":"Parse Warnings","type":"array"},"status":{"default":"ready","title":"Status","type":"string"},"uploaded_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uploaded At"},"uploaded_by_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uploaded By Uid"},"has_extracted_text":{"default":false,"title":"Has Extracted Text","type":"boolean"},"extracted_text_chars":{"default":0,"description":"Length of the stored extracted text (before the 12,000-character cap).","title":"Extracted Text Chars","type":"integer"},"has_structured_summary":{"default":false,"title":"Has Structured Summary","type":"boolean"},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First ~280 characters of the stored preview text.","title":"Preview"}},"required":["id","filename"],"title":"LibraryFile","type":"object"},"LinkedCampaignRef":{"properties":{"campaign_id":{"title":"Campaign Id","type":"string"},"title":{"title":"Title","type":"string"},"brand_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Name"},"display_brand_name":{"title":"Display Brand Name","type":"string"},"is_brand_fallback":{"default":false,"title":"Is Brand Fallback","type":"boolean"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"excluded_node_count":{"default":0,"description":"Nodes the campaign excludes across every cluster it links.","title":"Excluded Node Count","type":"integer"},"excluded_node_ids_in_cluster":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"default":null,"description":"This cluster's nodes the campaign excludes (known when node ids are loaded).","title":"Excluded Node Ids In Cluster"},"excluded_node_count_in_cluster":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Excluded Node Count In Cluster"},"included_node_count_in_cluster":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Included Node Count In Cluster"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"}},"required":["campaign_id","title","display_brand_name"],"title":"LinkedCampaignRef","type":"object"},"List":{"type":"object","required":["object","url","data","has_more","next_cursor","meta"],"properties":{"object":{"type":"string","const":"list"},"url":{"type":"string"},"data":{"type":"array","items":{}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."},"meta":{"type":"object","properties":{},"description":"The result's non-list fields (window, coverage, freshness, totals, note …)."}}},"ListAirChecksResult":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/AirCheckRow"},"title":"Rows","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"status_counts":{"additionalProperties":{"type":"integer"},"description":"Counts over the filtered rows.","title":"Status Counts","type":"object"},"groups":{"description":"Groups over the filtered rows (all pages) when group_by is set.","items":{"$ref":"#/components/schemas/AirCheckGroup"},"title":"Groups","type":"array"},"group_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Group By"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"campaigns_scanned":{"default":0,"title":"Campaigns Scanned","type":"integer"},"clusters_loaded":{"default":0,"title":"Clusters Loaded","type":"integer"},"clusters_skipped":{"default":0,"description":"Linked clusters beyond the fetch cap (narrow with campaign_id/brand/show_id).","title":"Clusters Skipped","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["rows","page","computed_at","cache_age_seconds"],"title":"ListAirChecksResult","type":"object"},"ListBrandsResult":{"properties":{"brands":{"items":{"$ref":"#/components/schemas/BrandRow"},"title":"Brands","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"precision":{"enum":["summary","nodes","none"],"title":"Precision","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["brands","page","precision","computed_at","cache_age_seconds"],"title":"ListBrandsResult","type":"object"},"ListCampaignsResult":{"properties":{"campaigns":{"items":{"$ref":"#/components/schemas/CampaignRow"},"title":"Campaigns","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"status_counts":{"additionalProperties":{"type":"integer"},"description":"Counts before the status filter (like the page chips).","title":"Status Counts","type":"object"},"brands":{"description":"Every brand name across the workspace's campaigns.","items":{"type":"string"},"title":"Brands","type":"array"},"unlinked_count":{"default":0,"description":"Campaigns with at least one unlinked slot (before filters).","title":"Unlinked Count","type":"integer"},"duplicate_count":{"default":0,"title":"Duplicate Count","type":"integer"},"totals":{"additionalProperties":true,"description":"Sums over the filtered rows: reach, budget, expected impressions, EMV.","title":"Totals","type":"object"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"sort_by":{"title":"Sort By","type":"string"},"precision":{"description":"'summary' rows use stored cluster summaries; 'nodes' loaded every linked cluster.","enum":["summary","nodes","none"],"title":"Precision","type":"string"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["campaigns","page","sort_by","precision","computed_at","cache_age_seconds"],"title":"ListCampaignsResult","type":"object"},"ListClustersResult":{"properties":{"clusters":{"items":{"$ref":"#/components/schemas/ClusterRow"},"title":"Clusters","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"totals":{"$ref":"#/components/schemas/ClusterTotals"},"window":{"$ref":"#/components/schemas/WindowInfo"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_cluster_freshness":{"additionalProperties":{"$ref":"#/components/schemas/ShowRefreshFreshness"},"description":"show id → newest cluster refresh / save.","title":"Show Cluster Freshness","type":"object"},"tag_options":{"additionalProperties":{"items":{"$ref":"#/components/schemas/TagOption"},"type":"array"},"title":"Tag Options","type":"object"},"brand_options":{"items":{"type":"string"},"title":"Brand Options","type":"array"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["clusters","page","totals","window","filters","show_ids","computed_at","cache_age_seconds"],"title":"ListClustersResult","type":"object"},"ListEpisodesResult":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"episodes":{"items":{"$ref":"#/components/schemas/EpisodeRow"},"title":"Episodes","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"episode_count":{"description":"Size of the show's full episode universe before filters (stored episodes ∪ chart rows ∪ Apple ∪ cluster-derived).","title":"Episode Count","type":"integer"},"filtered_count":{"description":"Rows matching the filters (== page.total).","title":"Filtered Count","type":"integer"},"with_cluster_count":{"description":"Episodes in the universe with a source cluster.","title":"With Cluster Count","type":"integer"},"view":{"enum":["simple","goals","benchmark"],"title":"View","type":"string"},"date_range":{"additionalProperties":true,"title":"Date Range","type":"object"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"tag_options":{"additionalProperties":{"items":{"$ref":"#/components/schemas/TagOption"},"type":"array"},"title":"Tag Options","type":"object"},"brand_options":{"items":{"type":"string"},"title":"Brand Options","type":"array"},"goals":{"anyOf":[{"$ref":"#/components/schemas/GoalsSummary"},{"type":"null"}],"default":null},"benchmark":{"anyOf":[{"$ref":"#/components/schemas/BenchmarkSummary"},{"type":"null"}],"default":null},"cluster_freshness":{"$ref":"#/components/schemas/ShowRefreshFreshness"},"freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show","episodes","page","episode_count","filtered_count","with_cluster_count","view","date_range","filters","cluster_freshness","computed_at","cache_age_seconds"],"title":"ListEpisodesResult","type":"object"},"ListIntegrationsResult":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/IntegrationRow"},"title":"Rows","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"summary":{"$ref":"#/components/schemas/IntegrationsSummary"},"platforms":{"description":"The 18 platform keys the Integrations page tracks, in its Audio → Content order.","items":{"type":"string"},"title":"Platforms","type":"array"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["rows","page","summary","platforms","show_ids","computed_at"],"title":"ListIntegrationsResult","type":"object"},"ListReportAutomationsResult":{"properties":{"automations":{"items":{"$ref":"#/components/schemas/ReportAutomationRow"},"title":"Automations","type":"array"},"total":{"title":"Total","type":"integer"},"enabled_count":{"default":0,"title":"Enabled Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["automations","total","computed_at","cache_age_seconds"],"title":"ListReportAutomationsResult","type":"object"},"ListReportsResult":{"properties":{"kind":{"enum":["reports","templates"],"title":"Kind","type":"string"},"reports":{"items":{"$ref":"#/components/schemas/ReportRow"},"title":"Reports","type":"array"},"templates":{"items":{"$ref":"#/components/schemas/ReportTemplateRow"},"title":"Templates","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"built_in_template_count":{"default":0,"title":"Built In Template Count","type":"integer"},"custom_template_count":{"default":0,"title":"Custom Template Count","type":"integer"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["kind","page","computed_at","cache_age_seconds"],"title":"ListReportsResult","type":"object"},"ListShowCategoriesResult":{"properties":{"categories":{"items":{"$ref":"#/components/schemas/CategoryEntry"},"title":"Categories","type":"array"},"total":{"title":"Total","type":"integer"},"placeholders_dropped":{"default":0,"description":"'Category N' placeholders skipped, like the analytics page.","title":"Placeholders Dropped","type":"integer"},"uncategorised_show_ids":{"items":{"type":"string"},"title":"Uncategorised Show Ids","type":"array"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"default":0.0,"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["categories","total","computed_at"],"title":"ListShowCategoriesResult","type":"object"},"ListShowsResult":{"properties":{"shows":{"items":{"$ref":"#/components/schemas/ShowRow"},"title":"Shows","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"filters":{"additionalProperties":true,"title":"Filters","type":"object"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["shows","page","filters","computed_at","cache_age_seconds"],"title":"ListShowsResult","type":"object"},"ListSponsorshipPackagesResult":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"window":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Override applied to every package (30 | 90 | 365); None keeps each package's own trailing window.","title":"Window"},"packages":{"items":{"$ref":"#/components/schemas/SponsorshipPackage"},"title":"Packages","type":"array"},"stats_by_window":{"additionalProperties":{"additionalProperties":{"$ref":"#/components/schemas/WindowStat"},"type":"object"},"description":"Trailing window ('30' | '90' | '365') → average reach per format (audio, video, short_form, newsletter).","title":"Stats By Window","type":"object"},"clusters_considered":{"default":0,"title":"Clusters Considered","type":"integer"},"clusters_available":{"default":0,"title":"Clusters Available","type":"integer"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["show_id","show_name","packages","computed_at","cache_age_seconds"],"title":"ListSponsorshipPackagesResult","type":"object"},"ListSubnetworksResult":{"properties":{"subnetworks":{"items":{"$ref":"#/components/schemas/SubnetworkSummary"},"title":"Subnetworks","type":"array"},"total":{"title":"Total","type":"integer"},"is_subnetwork":{"default":false,"title":"Is Subnetwork","type":"boolean"},"parent_network_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Parent Network Uid"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"}},"required":["subnetworks","total","computed_at","cache_age_seconds"],"title":"ListSubnetworksResult","type":"object"},"ListWorkspaceLibraryFilesResult":{"properties":{"files":{"items":{"$ref":"#/components/schemas/LibraryFile"},"title":"Files","type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"},"storage_configured":{"description":"True when a Storage bucket is configured, so `GET /v1/library/files/{file_id}` can sign download URLs.","title":"Storage Configured","type":"boolean"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["files","page","storage_configured","computed_at","cache_age_seconds"],"title":"ListWorkspaceLibraryFilesResult","type":"object"},"ManualClusterInput":{"additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"default":"","type":"string"},"image":{"default":"","type":"string"},"date":{"default":"","type":"string"}},"required":["name"],"type":"object"},"MatchInfo":{"properties":{"by":{"description":"What matched, e.g. 'spotify_episode_id', 'guid', 'simplecast_episode_id+title+date', 'title+published_on', 'title'.","title":"By","type":"string"},"confidence":{"enum":["exact","high","medium","low"],"title":"Confidence","type":"string"},"score":{"description":"0–1 similarity behind the confidence.","title":"Score","type":"number"},"reasons":{"items":{"type":"string"},"title":"Reasons","type":"array"}},"required":["by","confidence","score"],"title":"MatchInfo","type":"object"},"MatchSponsorsResult":{"properties":{"matches":{"items":{"$ref":"#/components/schemas/SponsorMatch"},"title":"Matches","type":"array"},"inventory_size":{"title":"Inventory Size","type":"integer"},"inventory_sources":{"additionalProperties":{"type":"integer"},"description":"Candidates per primary source.","title":"Inventory Sources","type":"object"},"context":{"additionalProperties":true,"description":"What was matched against: show, episode, brief.","title":"Context","type":"object"},"show_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Show Id"},"episode_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Id"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["matches","inventory_size","computed_at","cache_age_seconds"],"title":"MatchSponsorsResult","type":"object"},"NetworkOpportunity":{"properties":{"pair":{"title":"Pair","type":"string"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_names":{"items":{"type":"string"},"title":"Show Names","type":"array"},"reason":{"title":"Reason","type":"string"},"overlap_categories":{"items":{"type":"string"},"title":"Overlap Categories","type":"array"},"combined_collaborations":{"default":0,"title":"Combined Collaborations","type":"integer"},"combined_reach":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Sum of both shows' cluster reach (None when reach was not loaded).","title":"Combined Reach"},"shared_hosts":{"items":{"type":"string"},"title":"Shared Hosts","type":"array"},"score":{"title":"Score","type":"number"}},"required":["pair","show_ids","show_names","reason","score"],"title":"NetworkOpportunity","type":"object"},"PageInfo":{"properties":{"total":{"title":"Total","type":"integer"},"limit":{"title":"Limit","type":"integer"},"offset":{"title":"Offset","type":"integer"},"has_more":{"title":"Has More","type":"boolean"},"next_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Next Offset"}},"required":["total","limit","offset","has_more"],"title":"PageInfo","type":"object"},"ParseInsertionOrderResult":{"properties":{"ok":{"default":true,"title":"Ok","type":"boolean"},"configured":{"description":"False when this server cannot reach the app's extractor (internal key / app URL missing); nothing was parsed.","title":"Configured","type":"boolean"},"source":{"anyOf":[{"$ref":"#/components/schemas/InsertionOrderSource"},{"type":"null"}],"default":null},"io":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The extracted InsertionOrder (ioNumber, advertiser, flight, lineItems[], confidence, sourceQuotes …).","title":"Io"},"plan":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The app's CampaignPlan as returned (camelCase); proposed_create_campaign_args is the same plan in `POST /v1/campaigns`'s shape.","title":"Plan"},"proposed_create_campaign_args":{"anyOf":[{"$ref":"#/components/schemas/ProposedCreateCampaignArgs"},{"type":"null"}],"default":null},"unresolved_line_items":{"description":"Line items whose show could not be matched to a workspace show; ask the user, never guess.","items":{"$ref":"#/components/schemas/UnresolvedLineItem"},"title":"Unresolved Line Items","type":"array"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The extraction model the app used.","title":"Model"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["configured","computed_at","cache_age_seconds"],"title":"ParseInsertionOrderResult","type":"object"},"PastGuest":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"title":"Name","type":"string"},"title":{"default":"","title":"Title","type":"string"},"bio":{"default":"","title":"Bio","type":"string"},"photo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Photo"},"featured":{"default":false,"title":"Featured","type":"boolean"},"episode_link":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Link"}},"required":["name"],"title":"PastGuest","type":"object"},"PendingDataRequest":{"properties":{"id":{"title":"Id","type":"string"},"platform":{"title":"Platform","type":"string"},"status":{"title":"Status","type":"string"},"requested_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Requested At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Completed At"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"}},"required":["id","platform","status"],"title":"PendingDataRequest","type":"object"},"PlannedEpisodeInput":{"additionalProperties":false,"description":"One campaign slot (write-spec §2.4).","properties":{"show_id":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null},"expected_impressions":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"budget":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"default":null},"linked_cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null}},"required":["show_id"],"type":"object"},"PlatformState":{"properties":{"platform":{"title":"Platform","type":"string"},"connected":{"title":"Connected","type":"boolean"},"has_data":{"title":"Has Data","type":"boolean"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Updated"},"importing_state":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Importing State"},"freshness":{"anyOf":[{"$ref":"#/components/schemas/FreshnessEntry"},{"type":"null"}],"default":null}},"required":["platform","connected","has_data"],"title":"PlatformState","type":"object"},"PlatformStatsBlock":{"properties":{"platform":{"title":"Platform","type":"string"},"label":{"title":"Label","type":"string"},"connected":{"title":"Connected","type":"boolean"},"has_data":{"title":"Has Data","type":"boolean"},"importing_state":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Importing State"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"JS function the metric block ports (platformMetrics.calculate*Metrics).","title":"Source"},"metrics":{"additionalProperties":true,"description":"Ported metric block in snake_case (values for the window + *_growth vs the previous window).","title":"Metrics","type":"object"},"audience":{"additionalProperties":true,"description":"Demographics / geo / retention / traffic sources when the platform stores them.","title":"Audience","type":"object"},"freshness":{"$ref":"#/components/schemas/FreshnessEntry"},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Secret-stripped platform sub-document (include_raw=True only).","title":"Raw"},"raw_truncated":{"default":false,"title":"Raw Truncated","type":"boolean"},"window_totals":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Windows longer than 30 days (90d) only: this platform's reach/engagement over the full window and the previous one from the daily series + analyticsHistory, with growth (null when the platform's data covers < 50% of the previous window).","title":"Window Totals"}},"required":["platform","label","connected","has_data","freshness"],"title":"PlatformStatsBlock","type":"object"},"PodcastMetadata":{"properties":{"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider"},"provider_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider Id"},"provider_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider Url"},"rss_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Rss Url"},"spotify_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Spotify Id"},"apple_podcasts_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Apple Podcasts Id"},"total_episodes":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Episodes"},"average_episode_length_sec":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Average Episode Length Sec"},"imported_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Imported At"}},"title":"PodcastMetadata","type":"object"},"PodcastSearchResult":{"properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"publisher":{"default":"","title":"Publisher","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"description":{"default":"","title":"Description","type":"string"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"total_episodes":{"default":0,"title":"Total Episodes","type":"integer"},"audio_length_sec":{"default":0,"title":"Audio Length Sec","type":"integer"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Website"},"podchaser_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Podchaser Url"},"apple_podcasts_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Apple Podcasts Id"},"spotify_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Spotify Id"},"rss_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Rss Url"},"extra":{"additionalProperties":true,"title":"Extra","type":"object"}},"required":["id","title"],"title":"PodcastSearchResult","type":"object"},"PostGroup":{"properties":{"key":{"description":"Day (YYYY-MM-DD) or platform key.","title":"Key","type":"string"},"count":{"title":"Count","type":"integer"},"posts":{"items":{"$ref":"#/components/schemas/PostRecord"},"title":"Posts","type":"array"}},"required":["key","count","posts"],"title":"PostGroup","type":"object"},"PostMetrics":{"properties":{"views":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"title":"Views"},"likes":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"title":"Likes"},"comments":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"title":"Comments"},"shares":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"null"}],"default":null,"title":"Shares"}},"title":"PostMetrics","type":"object"},"PostRecord":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"platform":{"title":"Platform","type":"string"},"post_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Post Type"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Date"},"day":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Day"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Thumbnail"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caption"},"metrics":{"additionalProperties":true,"title":"Metrics","type":"object"}},"required":["show","platform"],"title":"PostRecord","type":"object"},"ProposedBrand":{"properties":{"name":{"title":"Name","type":"string"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"contact":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Contact"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Notes"}},"required":["name"],"title":"ProposedBrand","type":"object"},"ProposedCreateCampaignArgs":{"description":"Exactly the argument names ``POST /v1/campaigns`` accepts, ready to pass through.","properties":{"title":{"title":"Title","type":"string"},"description":{"default":"","title":"Description","type":"string"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"End Date"},"brand":{"anyOf":[{"$ref":"#/components/schemas/ProposedBrand"},{"type":"null"}],"default":null},"total_budget":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Total Budget"},"show_goals":{"additionalProperties":{"type":"integer"},"title":"Show Goals","type":"object"},"show_budgets":{"additionalProperties":{"type":"number"},"title":"Show Budgets","type":"object"},"planned_episodes":{"items":{"$ref":"#/components/schemas/ProposedPlannedEpisode"},"title":"Planned Episodes","type":"array"}},"required":["title"],"title":"ProposedCreateCampaignArgs","type":"object"},"ProposedPlannedEpisode":{"properties":{"show_id":{"title":"Show Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"expected_impressions":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Expected Impressions"},"budget":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Budget"}},"required":["show_id"],"title":"ProposedPlannedEpisode","type":"object"},"ReachCategory":{"properties":{"current":{"title":"Current","type":"integer"},"previous":{"title":"Previous","type":"integer"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Percent; None when the baseline window has < 50 % day coverage. On windows > 30 days (90d) it is like-for-like: only platforms with data across ≥ 50 % of the previous window are compared (None when none qualify).","title":"Growth"},"platforms":{"description":"Chart fields included in this category (after the platforms filter).","items":{"type":"string"},"title":"Platforms","type":"array"}},"required":["current","previous"],"title":"ReachCategory","type":"object"},"RefreshError":{"properties":{"node_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Node Id"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform"},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Kind"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Message"},"status":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Status"},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"At"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"}},"title":"RefreshError","type":"object"},"ReportAutomationRow":{"properties":{"id":{"title":"Id","type":"string"},"owner_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Owner Uid"},"title":{"title":"Title","type":"string"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Template Id"},"template_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Template Name"},"template_is_built_in":{"default":false,"title":"Template Is Built In","type":"boolean"},"element_ids":{"items":{"type":"string"},"title":"Element Ids","type":"array"},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Frequency"},"time_range":{"title":"Time Range","type":"string"},"time_range_label":{"title":"Time Range Label","type":"string"},"comparison_mode":{"title":"Comparison Mode","type":"string"},"selected_show_ids":{"items":{"type":"string"},"title":"Selected Show Ids","type":"array"},"selected_show_names":{"items":{"type":"string"},"title":"Selected Show Names","type":"array"},"delivery_method":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Delivery Method"},"recipient_email_masked":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Recipient Email Masked"},"slack_configured":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Slack Configured"},"enabled":{"default":true,"title":"Enabled","type":"boolean"},"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Start Date"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"last_run":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Run"},"next_run":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Next Run"},"last_report_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Report Id"},"last_report_urls":{"anyOf":[{"$ref":"#/components/schemas/ReportUrls"},{"type":"null"}],"default":null},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Error"},"last_error_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Error At"},"last_delivery_blocked":{"default":false,"title":"Last Delivery Blocked","type":"boolean"},"last_delivery_block_reasons":{"items":{"type":"string"},"title":"Last Delivery Block Reasons","type":"array"},"last_delivery_zero_kpi_count":{"default":0,"title":"Last Delivery Zero Kpi Count","type":"integer"}},"required":["id","title","time_range","time_range_label","comparison_mode"],"title":"ReportAutomationRow","type":"object"},"ReportElement":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"instance_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Instance Id"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Type"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Category"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"metric":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Metric"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform"},"chart_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Chart Type"},"text_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Text Type"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Content"},"max_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Rows"},"has_episode_data":{"default":false,"title":"Has Episode Data","type":"boolean"}},"title":"ReportElement","type":"object"},"ReportHeadline":{"properties":{"total":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Total"},"total_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Total Growth"},"youtube":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Youtube"},"youtube_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Youtube Growth"},"audio":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Audio"},"audio_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Audio Growth"},"social":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Social"},"social_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Social Growth"}},"title":"ReportHeadline","type":"object"},"ReportRow":{"properties":{"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"network_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Network Name"},"time_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Time Range"},"comparison_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Comparison Mode"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created By"},"created_via":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created Via"},"is_automated":{"default":false,"title":"Is Automated","type":"boolean"},"is_test":{"default":false,"title":"Is Test","type":"boolean"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Template Id"},"element_count":{"default":0,"title":"Element Count","type":"integer"},"element_ids":{"items":{"type":"string"},"title":"Element Ids","type":"array"},"element_metrics":{"items":{"type":"string"},"title":"Element Metrics","type":"array"},"element_types":{"additionalProperties":{"type":"integer"},"title":"Element Types","type":"object"},"report_scope":{"anyOf":[{"$ref":"#/components/schemas/ReportScope"},{"type":"null"}],"default":null},"headline":{"$ref":"#/components/schemas/ReportHeadline"},"has_data":{"default":false,"title":"Has Data","type":"boolean"},"urls":{"$ref":"#/components/schemas/ReportUrls"}},"required":["id","title","headline","urls"],"title":"ReportRow","type":"object"},"ReportScope":{"properties":{"is_single_show":{"default":false,"title":"Is Single Show","type":"boolean"},"scope_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Scope Label"},"detail_text":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Detail Text"},"show_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Show Count"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_names":{"items":{"type":"string"},"title":"Show Names","type":"array"}},"title":"ReportScope","type":"object"},"ReportTemplateRow":{"properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"icon":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Icon"},"built_in":{"title":"Built In","type":"boolean"},"automation":{"description":"True when the template can drive a report automation.","title":"Automation","type":"boolean"},"dynamic":{"default":false,"title":"Dynamic","type":"boolean"},"element_count":{"default":0,"title":"Element Count","type":"integer"},"element_ids":{"items":{"type":"string"},"title":"Element Ids","type":"array"},"elements":{"description":"Custom templates only (built-ins carry element_ids).","items":{"$ref":"#/components/schemas/ReportElement"},"title":"Elements","type":"array"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["id","name","built_in","automation"],"title":"ReportTemplateRow","type":"object"},"ReportUrls":{"properties":{"network":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"https://network.listener.com/report/{uid}/{id}","title":"Network"},"public":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"https://listener.com/report/{uid}/{id}","title":"Public"}},"title":"ReportUrls","type":"object"},"SearchEpisodeRow":{"properties":{"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"youtube_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Reach"},"youtube_long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Long Form Reach"},"youtube_shorts_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Youtube Shorts Reach"},"audio_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Audio Reach"},"social_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Social Reach"},"long_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Long Form Reach"},"short_form_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Short Form Reach"},"long_form_count":{"default":0,"title":"Long Form Count","type":"integer"},"short_form_count":{"default":0,"title":"Short Form Count","type":"integer"},"clips":{"default":0,"title":"Clips","type":"integer"},"posts":{"default":0,"title":"Posts","type":"integer"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Percent (1.93 == 1.93 %).","title":"Engagement Rate"},"id":{"title":"Id","type":"string"},"title":{"title":"Title","type":"string"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"YYYY-MM-DD parsed with the app's date rules; null when the stored date is unreadable.","title":"Published At"},"date_raw":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Date Raw"},"duration":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Duration"},"duration_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Duration Seconds"},"episode_number":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Episode Number"},"source_platform":{"description":"'spotify' | 'apple' | 'youtube' | 'manual' | 'cluster' | provider key | 'unknown'.","title":"Source Platform","type":"string"},"platform_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Platform Label"},"is_manual":{"default":false,"title":"Is Manual","type":"boolean"},"is_external":{"default":false,"title":"Is External","type":"boolean"},"is_synthetic":{"default":false,"description":"Row invented by the app for a chart / Apple entry without a stored episode.","title":"Is Synthetic","type":"boolean"},"explicit":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"title":"Explicit"},"cover":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cover"},"share_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Share Url"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Truncated in list rows; full text on `GET /v1/shows/{show_id}/episodes/{episode_id}`.","title":"Description"},"tags":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"{series, format, guests}.","title":"Tags","type":"object"},"brands":{"description":"Sponsored-node brands and linked campaign brands on the source cluster.","items":{"type":"string"},"title":"Brands","type":"array"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Id"},"has_cluster":{"default":false,"description":"A source cluster exists or any reach / clips / posts > 0 (the page's rule).","title":"Has Cluster","type":"boolean"},"cluster_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Type"},"metrics_source":{"default":"none","title":"Metrics Source","type":"string"},"summary_stale":{"default":false,"title":"Summary Stale","type":"boolean"},"freshness":{"$ref":"#/components/schemas/ClusterFreshness2"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"refresh_error_count":{"default":0,"title":"Refresh Error Count","type":"integer"},"cluster_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster Public Url"},"cluster_app_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Cluster App Url"},"goals":{"anyOf":[{"$ref":"#/components/schemas/EpisodeGoals"},{"type":"null"}],"default":null},"benchmark":{"anyOf":[{"$ref":"#/components/schemas/EpisodeBenchmark"},{"type":"null"}],"default":null},"show":{"$ref":"#/components/schemas/ShowRef"},"search_score":{"default":0,"title":"Search Score","type":"number"}},"required":["id","title","source_platform","freshness","show"],"title":"SearchEpisodeRow","type":"object"},"SearchEpisodesResult":{"properties":{"query":{"title":"Query","type":"string"},"episodes":{"items":{"$ref":"#/components/schemas/SearchEpisodeRow"},"title":"Episodes","type":"array"},"total_matches":{"title":"Total Matches","type":"integer"},"limit":{"title":"Limit","type":"integer"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"searched_episode_count":{"description":"Episodes scanned across the scoped shows.","title":"Searched Episode Count","type":"integer"},"missing_show_ids":{"items":{"type":"string"},"title":"Missing Show Ids","type":"array"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["query","episodes","total_matches","limit","show_ids","searched_episode_count","computed_at","cache_age_seconds"],"title":"SearchEpisodesResult","type":"object"},"SearchPodcastsResult":{"properties":{"query":{"title":"Query","type":"string"},"configured":{"title":"Configured","type":"boolean"},"results":{"items":{"$ref":"#/components/schemas/PodcastSearchResult"},"title":"Results","type":"array"},"total":{"default":0,"title":"Total","type":"integer"},"source":{"default":"podchaser","title":"Source","type":"string"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["query","configured","computed_at","cache_age_seconds"],"title":"SearchPodcastsResult","type":"object"},"SearchedAccount":{"properties":{"id":{"description":"'<platform>:<handle>'.","title":"Id","type":"string"},"posts":{"default":0,"title":"Posts","type":"integer"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"}},"required":["id"],"title":"SearchedAccount","type":"object"},"SeriesPoint":{"properties":{"day":{"title":"Day","type":"string"},"date":{"description":"Short label as the chart shows it ('Sep 10').","title":"Date","type":"string"},"value":{"title":"Value","type":"number"}},"required":["day","date","value"],"title":"SeriesPoint","type":"object"},"ShowCandidate":{"properties":{"show_id":{"title":"Show Id","type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Score"}},"required":["show_id"],"title":"ShowCandidate","type":"object"},"ShowRankingRow":{"properties":{"rank":{"title":"Rank","type":"integer"},"show":{"$ref":"#/components/schemas/ShowRef"},"total":{"title":"Total","type":"integer"},"youtube":{"title":"Youtube","type":"integer"},"audio":{"title":"Audio","type":"integer"},"social":{"title":"Social","type":"integer"},"newsletter":{"default":0,"title":"Newsletter","type":"integer"},"per_platform":{"additionalProperties":{"type":"integer"},"title":"Per Platform","type":"object"},"previous_total":{"title":"Previous Total","type":"integer"},"previous_youtube":{"default":0,"title":"Previous Youtube","type":"integer"},"previous_audio":{"default":0,"title":"Previous Audio","type":"integer"},"previous_social":{"default":0,"title":"Previous Social","type":"integer"},"growth":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Growth"},"days_with_data":{"default":0,"title":"Days With Data","type":"integer"},"previous_days_with_data":{"default":0,"title":"Previous Days With Data","type":"integer"}},"required":["rank","show","total","youtube","audio","social","previous_total"],"title":"ShowRankingRow","type":"object"},"ShowRef":{"description":"The minimal show reference embedded in cross-show results.","properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"handle":{"default":"","title":"Handle","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"}},"required":["id","name"],"title":"ShowRef","type":"object"},"ShowRefreshFreshness":{"description":"``getShowRefreshFreshness``: newest refresh across a show's clusters.","properties":{"kind":{"default":"unknown","title":"Kind","type":"string"},"at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"At"},"last_refreshed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Refreshed At"},"failed_node_count":{"default":0,"title":"Failed Node Count","type":"integer"},"clusters_with_errors":{"default":0,"title":"Clusters With Errors","type":"integer"}},"title":"ShowRefreshFreshness","type":"object"},"ShowRefreshStatus":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"newest_platform_update":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Newest Platform Update"},"newest_platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Newest Platform"},"connected_platforms":{"items":{"type":"string"},"title":"Connected Platforms","type":"array"},"platform_freshness":{"additionalProperties":{"$ref":"#/components/schemas/FreshnessEntry"},"title":"Platform Freshness","type":"object"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"refreshable_stale_platforms":{"description":"Stale platforms `POST /v1/shows/{show_id}/platforms/{platform}/refresh` can refresh (server kind).","items":{"type":"string"},"title":"Refreshable Stale Platforms","type":"array"},"request_only_stale_platforms":{"description":"Stale platforms only an ops request can refresh (Spotify/Apple).","items":{"type":"string"},"title":"Request Only Stale Platforms","type":"array"},"last_cluster_update":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Cluster Update"},"last_update_stats":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Last Update Stats"},"cluster_freshness":{"anyOf":[{"$ref":"#/components/schemas/ClusterFreshness"},{"type":"null"}],"default":null},"pending_data_requests":{"items":{"$ref":"#/components/schemas/PendingDataRequest"},"title":"Pending Data Requests","type":"array"},"recent_data_requests":{"description":"Latest completed/failed request per platform.","items":{"$ref":"#/components/schemas/PendingDataRequest"},"title":"Recent Data Requests","type":"array"}},"required":["show"],"title":"ShowRefreshStatus","type":"object"},"ShowRow":{"properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"handle":{"default":"","title":"Handle","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"plan":{"title":"Plan","type":"string"},"connected_platforms":{"items":{"type":"string"},"title":"Connected Platforms","type":"array"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"episode_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Known episode total from Spotify/metadata; `GET /v1/shows/{show_id}/episodes` returns the exact indexed count.","title":"Episode Count"},"description":{"default":"","title":"Description","type":"string"},"author":{"default":"","title":"Author","type":"string"},"hidden_categories":{"items":{"type":"string"},"title":"Hidden Categories","type":"array"},"is_hidden":{"default":false,"title":"Is Hidden","type":"boolean"},"agency_managed":{"default":false,"title":"Agency Managed","type":"boolean"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"last_cluster_update":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Cluster Update"},"host_names":{"items":{"type":"string"},"title":"Host Names","type":"array"},"app_url":{"title":"App Url","type":"string"}},"required":["id","name","plan","app_url"],"title":"ShowRow","type":"object"},"ShowSeriesRow":{"properties":{"date":{"title":"Date","type":"string"},"total":{"title":"Total","type":"integer"}},"required":["date","total"],"title":"ShowSeriesRow","type":"object"},"ShowSummary":{"properties":{"id":{"title":"Id","type":"string"},"name":{"title":"Name","type":"string"},"handle":{"default":"","title":"Handle","type":"string"},"image":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Image"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"},"categories":{"items":{"type":"string"},"title":"Categories","type":"array"},"plan":{"title":"Plan","type":"string"},"connected_platforms":{"items":{"type":"string"},"title":"Connected Platforms","type":"array"},"stale_platforms":{"items":{"type":"string"},"title":"Stale Platforms","type":"array"},"episode_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Known episode total from Spotify/metadata; `GET /v1/shows/{show_id}/episodes` returns the exact indexed count.","title":"Episode Count"}},"required":["id","name","plan"],"title":"ShowSummary","type":"object"},"ShowTalent":{"properties":{"show_id":{"title":"Show Id","type":"string"},"show_name":{"title":"Show Name","type":"string"},"talent":{"items":{"$ref":"#/components/schemas/TalentMember"},"title":"Talent","type":"array"}},"required":["show_id","show_name","talent"],"title":"ShowTalent","type":"object"},"SimplecastEpisodeRef":{"properties":{"id":{"title":"Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"listeners":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Listeners"}},"required":["id"],"title":"SimplecastEpisodeRef","type":"object"},"SourceHandle":{"properties":{"id":{"description":"'<platform>:<handle lowercased>'.","title":"Id","type":"string"},"platform":{"title":"Platform","type":"string"},"handle":{"title":"Handle","type":"string"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Name"},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Avatar"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"origin":{"description":"connected (linked to the show) | learned (seen in past clusters) | added (by a person).","title":"Origin","type":"string"},"role":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Role"},"enabled":{"title":"Enabled","type":"boolean"},"learned_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Nodes from this account in the show's past clusters (learned only).","title":"Learned Count"},"learned_share":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"0-1 share of the show's past cluster nodes (learned only).","title":"Learned Share"},"last_fetched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Fetched At"},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Last Error"}},"required":["id","platform","handle","origin","enabled"],"title":"SourceHandle","type":"object"},"SourceHandleInput":{"additionalProperties":false,"description":"An account to add to a show's sources: a URL, `@handle` or `platform:handle`.\n\nA bare string is accepted (`\"https://www.tiktok.com/@dugoutdaily\"`,\n`\"x:northwindaudio\"`); `platform` is needed only for a bare `@handle`.","properties":{"handle":{"description":"Profile URL, `platform:handle`, or `@handle` (then `platform` is required).","type":"string"},"platform":{"anyOf":[{"enum":["tiktok","instagram","facebook","x","youtube","threads","linkedin"],"type":"string"},{"type":"null"}],"default":null},"role":{"anyOf":[{"enum":["own","partner","guest"],"type":"string"},{"type":"null"}],"default":null,"description":"own (the client's brand), partner (default for added accounts) or guest."}},"required":["handle"],"type":"object"},"SourceWindow":{"properties":{"before_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Posts up to this many days before the episode date count.","title":"Before Days"},"after_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Posts up to this many days after the episode date count.","title":"After Days"},"learned_from":{"anyOf":[{},{"type":"null"}],"default":null,"title":"Learned From"}},"title":"SourceWindow","type":"object"},"SponsorMatch":{"properties":{"sponsor_id":{"title":"Sponsor Id","type":"string"},"name":{"title":"Name","type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Slug"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Domain"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Logo"},"source":{"description":"Primary source: campaign_brand | brand_invite | brand_profile | network_sponsor | cluster_sponsor | collaboration.","title":"Source","type":"string"},"sources":{"items":{"type":"string"},"title":"Sources","type":"array"},"fit_score":{"title":"Fit Score","type":"integer"},"matched_terms":{"items":{"type":"string"},"title":"Matched Terms","type":"array"},"reason":{"title":"Reason","type":"string"},"proof_points":{"items":{"type":"string"},"title":"Proof Points","type":"array"},"campaign_count":{"default":0,"title":"Campaign Count","type":"integer"},"invite_status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Invite Status"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Industry"},"brand_public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Brand Public Url"}},"required":["sponsor_id","name","source","fit_score","reason"],"title":"SponsorMatch","type":"object"},"SponsorshipPackage":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"default":"","title":"Name","type":"string"},"description":{"default":"","title":"Description","type":"string"},"price":{"default":"","title":"Price","type":"string"},"trailing_window":{"title":"Trailing Window","type":"integer"},"window_days":{"title":"Window Days","type":"integer"},"format_averages":{"items":{"type":"string"},"title":"Format Averages","type":"array"},"featured":{"default":false,"title":"Featured","type":"boolean"},"enabled":{"default":true,"title":"Enabled","type":"boolean"},"deliverables":{"items":{"$ref":"#/components/schemas/Deliverable"},"title":"Deliverables","type":"array"},"projected_reach":{"default":0,"title":"Projected Reach","type":"number"},"verified_reach":{"default":0,"title":"Verified Reach","type":"number"}},"required":["trailing_window","window_days"],"title":"SponsorshipPackage","type":"object"},"SpotifyRating":{"properties":{"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Rating"},"total_ratings":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Ratings"},"total_episodes":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Episodes"}},"title":"SpotifyRating","type":"object"},"SubclusterRollup":{"description":"``aggregateNodesBySubcluster`` row: a labelled anchor plus every clip / post hanging beneath it.","properties":{"key":{"title":"Key","type":"string"},"name":{"title":"Name","type":"string"},"anchor_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The anchor node id (null on the 'Not in a subcluster' row).","title":"Anchor Id"},"anchor_label":{"default":"","title":"Anchor Label","type":"string"},"is_unassigned":{"default":false,"description":"True on the trailing 'Not in a subcluster' row (episodes and loose pieces).","title":"Is Unassigned","type":"boolean"},"member_ids":{"description":"Content node ids in this row, the anchor first.","items":{"type":"string"},"title":"Member Ids","type":"array"},"pieces":{"default":0,"title":"Pieces","type":"integer"},"reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Reach"},"engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Engagement Rate"},"share_of_reach":{"default":0,"title":"Share Of Reach","type":"number"},"platforms":{"items":{"$ref":"#/components/schemas/TagPlatformSlice"},"title":"Platforms","type":"array"}},"required":["key","name"],"title":"SubclusterRollup","type":"object"},"SubclusterRollups":{"description":"The cluster's subclusters, as the canvas Subclusters list and the Cluster Analytics 'Subcluster' tab show them.","properties":{"rows":{"items":{"$ref":"#/components/schemas/SubclusterRollup"},"title":"Rows","type":"array"},"subcluster_count":{"default":0,"title":"Subcluster Count","type":"integer"},"average_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"description":"Mean reach per subcluster (the canvas header's 'Avg. subcluster reach').","title":"Average Reach"},"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"content_node_count":{"default":0,"title":"Content Node Count","type":"integer"},"grouped_node_count":{"default":0,"title":"Grouped Node Count","type":"integer"},"unassigned_node_count":{"default":0,"title":"Unassigned Node Count","type":"integer"},"multi_subcluster_node_count":{"default":0,"title":"Multi Subcluster Node Count","type":"integer"},"has_subclusters":{"default":false,"title":"Has Subclusters","type":"boolean"}},"title":"SubclusterRollups","type":"object"},"SubnetworkSummary":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"title":"Name","type":"string"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handle"},"logo":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Logo"},"show_ids":{"items":{"type":"string"},"title":"Show Ids","type":"array"},"show_count":{"default":0,"title":"Show Count","type":"integer"},"unknown_show_ids":{"description":"Show ids listed on the subnetwork but not in the parent's managedKits.","items":{"type":"string"},"title":"Unknown Show Ids","type":"array"},"is_activated":{"default":false,"title":"Is Activated","type":"boolean"},"account_uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Account Uid"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Created At"},"public_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public Url"}},"required":["name"],"title":"SubnetworkSummary","type":"object"},"SuggestionEpisode":{"properties":{"episode_id":{"title":"Episode Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"status":{"title":"Status","type":"string"},"mode":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Mode"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Run Id"},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Set when a cluster already exists (auto mode or after accepting).","title":"Cluster Id"},"added_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Added Count"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"items_total":{"default":0,"title":"Items Total","type":"integer"},"sure_count":{"default":0,"title":"Sure Count","type":"integer"},"likely_count":{"default":0,"title":"Likely Count","type":"integer"},"possible_count":{"default":0,"title":"Possible Count","type":"integer"},"external_count":{"default":0,"title":"External Count","type":"integer"},"items":{"items":{"$ref":"#/components/schemas/SuggestionItem"},"title":"Items","type":"array"},"review_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Review Url"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Updated At"}},"required":["episode_id","status"],"title":"SuggestionEpisode","type":"object"},"SuggestionItem":{"properties":{"key":{"description":"Pass to `POST /v1/shows/{show_id}/cluster-suggestions/{episode_id}/review`.","title":"Key","type":"string"},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Display label (TikTok, YouTube Shorts, X …).","title":"Platform"},"platform_key":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Internal slug (tiktok, youtube_short, x …).","title":"Platform Key"},"canonical_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Canonical Id"},"matched_by":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Matched By"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"thumbnail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Thumbnail"},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Published At"},"confidence":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Confidence"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"sure | likely | possible (less certain; never added automatically, offer it last).","title":"Label"},"auto_write":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True when auto mode would add this post by itself (the show's gate allows it).","title":"Auto Write"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Reason"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"library (connected accounts) | external (not in the library).","title":"Source"},"handle":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Handle"},"origin":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Origin"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/PostMetrics"},{"type":"null"}],"default":null}},"required":["key"],"title":"SuggestionItem","type":"object"},"SurveyData":{"properties":{"how_did_you_find":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"How Did You Find"},"what_are_you_looking_for":{"items":{"type":"string"},"title":"What Are You Looking For","type":"array"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Completed At"}},"title":"SurveyData","type":"object"},"TagOption":{"properties":{"value":{"title":"Value","type":"string"},"count":{"title":"Count","type":"integer"}},"required":["value","count"],"title":"TagOption","type":"object"},"TagPlatformSlice":{"properties":{"platform":{"title":"Platform","type":"string"},"pieces":{"default":0,"title":"Pieces","type":"integer"},"reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Reach"}},"required":["platform"],"title":"TagPlatformSlice","type":"object"},"TagRollup":{"description":"``aggregateNodesByTag`` row: one custom tag across the cluster's content nodes.","properties":{"tag":{"title":"Tag","type":"string"},"key":{"title":"Key","type":"string"},"is_untagged":{"default":false,"title":"Is Untagged","type":"boolean"},"pieces":{"default":0,"title":"Pieces","type":"integer"},"reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Reach"},"engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Engagement"},"engagement_rate":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Engagement Rate"},"share_of_reach":{"default":0,"title":"Share Of Reach","type":"number"},"platforms":{"items":{"$ref":"#/components/schemas/TagPlatformSlice"},"title":"Platforms","type":"array"}},"required":["tag","key"],"title":"TagRollup","type":"object"},"TagRollups":{"properties":{"rows":{"items":{"$ref":"#/components/schemas/TagRollup"},"title":"Rows","type":"array"},"total_reach":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Reach"},"total_engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"default":0,"title":"Total Engagement"},"content_node_count":{"default":0,"title":"Content Node Count","type":"integer"},"tagged_node_count":{"default":0,"title":"Tagged Node Count","type":"integer"},"untagged_node_count":{"default":0,"title":"Untagged Node Count","type":"integer"},"multi_tagged_node_count":{"default":0,"title":"Multi Tagged Node Count","type":"integer"},"has_tags":{"default":false,"title":"Has Tags","type":"boolean"}},"title":"TagRollups","type":"object"},"TalentMember":{"properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Masked: j***@domain","title":"Email"},"uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uid"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Status"},"role":{"default":"talent","title":"Role","type":"string"},"invited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Invited At"},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Accepted At"}},"title":"TalentMember","type":"object"},"TeamMember":{"properties":{"email":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Masked: j***@domain","title":"Email"},"uid":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Uid"},"status":{"default":"pending","title":"Status","type":"string"},"role":{"default":"member","title":"Role","type":"string"},"invited_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Invited At"},"accepted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Accepted At"}},"title":"TeamMember","type":"object"},"TimelinePoint":{"properties":{"date":{"title":"Date","type":"string"},"views":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Views"},"engagement":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Engagement"}},"required":["date","views","engagement"],"title":"TimelinePoint","type":"object"},"TimelineRow":{"properties":{"date":{"title":"Date","type":"string"},"total":{"title":"Total","type":"integer"},"per_platform":{"additionalProperties":{"type":"integer"},"title":"Per Platform","type":"object"},"cumulative":{"default":0,"description":"Running total of `total` from the first day of the window.","title":"Cumulative","type":"integer"}},"required":["date","total"],"title":"TimelineRow","type":"object"},"TopContentItem":{"properties":{"show":{"$ref":"#/components/schemas/ShowRef"},"platform":{"title":"Platform","type":"string"},"post_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Post Type"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Date"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Url"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"caption":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Caption"},"metrics":{"additionalProperties":true,"title":"Metrics","type":"object"},"primary_metric":{"title":"Primary Metric","type":"string"},"primary_value":{"title":"Primary Value","type":"number"}},"required":["show","platform","primary_metric","primary_value"],"title":"TopContentItem","type":"object"},"UnresolvedLineItem":{"properties":{"line_item_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Line Item Index"},"show_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The show name as printed on the IO.","title":"Show Name"},"units":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Units"},"impressions":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Impressions"},"cost":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Cost"},"placement":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Placement"},"candidates":{"description":"Workspace shows that may match, best first.","items":{"$ref":"#/components/schemas/ShowCandidate"},"title":"Candidates","type":"array"}},"title":"UnresolvedLineItem","type":"object"},"WebResearchResult":{"properties":{"query":{"title":"Query","type":"string"},"configured":{"title":"Configured","type":"boolean"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Summary"},"sources":{"items":{"$ref":"#/components/schemas/WebResearchSource"},"title":"Sources","type":"array"},"total_results":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Total Results"},"computed_at":{"title":"Computed At","type":"string"},"cache_age_seconds":{"title":"Cache Age Seconds","type":"number"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Note"}},"required":["query","configured","computed_at","cache_age_seconds"],"title":"WebResearchResult","type":"object"},"WebResearchSource":{"properties":{"title":{"title":"Title","type":"string"},"url":{"title":"Url","type":"string"},"snippet":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Snippet"},"display_link":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Display Link"}},"required":["title","url"],"title":"WebResearchSource","type":"object"},"WebhookDelivery":{"type":"object","required":["object","id","endpoint_id","event_id","status"],"properties":{"object":{"const":"webhook_delivery"},"id":{"type":"string","description":"wd_…"},"endpoint_id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attempts":{"type":"array","items":{"type":"object"}},"next_attempt_at":{"type":["string","null"],"format":"date-time"},"response_status":{"type":["integer","null"]},"response_body_excerpt":{"type":["string","null"]},"duration_ms":{"type":["number","null"]},"created_at":{"type":"string","format":"date-time"}}},"WebhookEndpoint":{"type":"object","required":["object","id","url","enabled_events","status"],"properties":{"object":{"const":"webhook_endpoint"},"id":{"type":"string","description":"we_…"},"url":{"type":"string","format":"uri"},"description":{"type":["string","null"]},"enabled_events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["enabled","disabled"]},"disabled_reason":{"type":["string","null"]},"secret":{"type":"string","description":"whsec_… — returned only on create and roll-secret."},"secret_last4":{"type":"string"},"expires_previous_at":{"type":["string","null"],"format":"date-time"},"api_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"WebhookEndpointSecret":{"type":"object","required":["object","id","secret"],"properties":{"object":{"const":"webhook_endpoint_secret"},"id":{"type":"string","description":"we_…"},"secret":{"type":"string","description":"whsec_… — verify Listener-Signature with it."},"secret_last4":{"type":["string","null"]},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"Set while a rolled secret still signs deliveries."}}},"WindowInfo":{"description":"The resolved analytics window (from ``core.dates.Window.as_dict()``).","properties":{"time_range":{"description":"Normalised token: '30d', '2026-Q2', '2026-01-01..2026-03-31', 'all'.","title":"Time Range","type":"string"},"kind":{"description":"'rolling' | 'quarter' | 'custom' | 'all'.","title":"Kind","type":"string"},"start":{"description":"First day (YYYY-MM-DD, inclusive, UTC).","title":"Start","type":"string"},"end":{"description":"Last day (YYYY-MM-DD, inclusive, UTC).","title":"End","type":"string"},"days":{"title":"Days","type":"integer"},"previous_start":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Previous Start"},"previous_end":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Previous End"}},"required":["time_range","kind","start","end","days"],"title":"WindowInfo","type":"object"},"WindowStat":{"properties":{"average":{"default":0,"title":"Average","type":"number"},"count":{"default":0,"title":"Count","type":"integer"},"open_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Open Rate"}},"title":"WindowStat","type":"object"},"WriteResult":{"description":"Every write tool returns exactly this (write-spec §1.3).\n\n``written`` is the exact payload with Firestore sentinels rendered as\n``\"<serverTimestamp>\"``, ``\"<arrayUnion:[…]>\"``, ``\"<deleteField>\"``.\n``data`` carries tool-specific extras (``campaign_id``, ``not_found`` …).","properties":{"ok":{"default":true,"title":"Ok","type":"boolean"},"dry_run":{"default":false,"title":"Dry Run","type":"boolean"},"auth_mode":{"default":"api_key","enum":["api_key","firebase_id_token","dev","dev_uid","dev_key","unknown"],"title":"Auth Mode","type":"string"},"path":{"default":"","title":"Path","type":"string"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Id"},"method":{"default":"none","enum":["add","set","set-merge","update","transaction","batch","delete","http","none"],"title":"Method","type":"string"},"written":{"additionalProperties":true,"title":"Written","type":"object"},"warnings":{"items":{"type":"string"},"title":"Warnings","type":"array"},"urls":{"$ref":"#/components/schemas/WriteUrls"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Error"},"data":{"additionalProperties":true,"title":"Data","type":"object"},"replayed":{"default":false,"title":"Replayed","type":"boolean"}},"title":"WriteResult","type":"object"},"WriteResultResponse":{"allOf":[{"$ref":"#/components/schemas/WriteResult"},{"type":"object","required":["object","resource"],"properties":{"object":{"type":"string","const":"write_result"},"resource":{"type":"string","description":"What was written (campaign, cluster, report …)."}}}]},"WriteUrls":{"properties":{"app":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"App"},"public":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Public"}},"title":"WriteUrls","type":"object"}},"responses":{"BadRequest":{"description":"Invalid request: missing, unknown or invalid parameters, malformed JSON, unknown version.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"Unknown show id: abc123. Valid show ids in this workspace: Uf9fDh5AsUp8Xr0Hi3Jb7GmZf1Gp, Am0QyL5tAd4Dr5Zg2Km8WqOp7Sto.","param":"show_id","doc_url":"https://developers.listener.com/docs/errors","request_id":"req_9m9ReX1wIa7Na0TpP6eG"}}}}},"Unauthorized":{"description":"Missing, invalid, expired or revoked credential.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"authentication_error","code":"credential_invalid","message":"Invalid credential. Check the key, or create a new one in Settings → Developers.","doc_url":"https://developers.listener.com/docs/errors#credential_invalid","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"Forbidden":{"description":"The credential lacks the required scope, or writes are disabled.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"permission_error","code":"scope_missing","message":"This credential lacks the 'campaigns:write' scope required by POST /v1/campaigns.","required_scope":"campaigns:write","doc_url":"https://developers.listener.com/docs/errors#scope_missing","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"NotFound":{"description":"The resource is not in this workspace.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Campaign 'Kq7mTz2Wv9LcR4pXa1Bn' was not found in this workspace.","doc_url":"https://developers.listener.com/docs/errors#resource_not_found","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"Conflict":{"description":"Confirmation required, or an Idempotency-Key request is still in flight.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"conflict_error","code":"confirmation_required","message":"This request needs \"confirm\": true. This permanently deletes the campaign (no undo, no cascade). Review error.preview, then send it again with \"confirm\": true.","param":"confirm","preview":{"deleted":true,"campaign":{"id":"Kq7mTz2Wv9LcR4pXa1Bn","title":"Acme Coffee — Fall Flight","slots":4}},"doc_url":"https://developers.listener.com/docs/errors#confirmation_required","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"PayloadTooLarge":{"description":"The request body exceeds 1 MB.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"invalid_request_error","code":"body_too_large","message":"Request bodies are limited to 1 MB.","doc_url":"https://developers.listener.com/docs/errors#body_too_large","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"TooManyRequests":{"description":"Rate limited. Retry after the Retry-After seconds.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"rate_limit_error","code":"rate_limited","message":"Too many requests. Retry after 12 s.","doc_url":"https://developers.listener.com/docs/errors#rate_limited","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}},"ServerError":{"description":"Something failed on Listener's side. Retry with the same Idempotency-Key.","headers":{"Request-Id":{"$ref":"#/components/headers/Request-Id"},"Listener-Version":{"$ref":"#/components/headers/Listener-Version"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"api_error","code":"internal_error","message":"Internal error. Request id: req_8f2LkQ0aZx1Vb7NcR3tY.","doc_url":"https://developers.listener.com/docs/errors#internal_error","request_id":"req_8f2LkQ0aZx1Vb7NcR3tY"}}}}}},"headers":{"Request-Id":{"description":"Unique id of this request (req_…). Quote it to support.","schema":{"type":"string"}},"Listener-Version":{"description":"The API version that served the request.","schema":{"type":"string"}},"RateLimit-Limit":{"description":"Requests allowed per minute for this credential.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the budget is full again.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Alias of RateLimit-Limit.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Alias of RateLimit-Remaining.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Alias of RateLimit-Reset.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying (429 only).","schema":{"type":"integer"}},"ETag":{"description":"Weak validator for If-None-Match (GET only).","schema":{"type":"string"}},"Idempotent-Replayed":{"description":"true when the response is a stored Idempotency-Key replay.","schema":{"type":"string"}}},"parameters":{"ListenerVersion":{"name":"Listener-Version","in":"header","required":false,"description":"API version (YYYY-MM-DD). Omit for the latest (2026-10-14).","schema":{"type":"string","enum":["2026-10-14"]}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.","schema":{"type":"string","maxLength":255}},"IfNoneMatch":{"name":"If-None-Match","in":"header","required":false,"description":"An ETag from a previous response; unchanged results answer 304.","schema":{"type":"string"}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"lsk_… API key or lat_… OAuth access token","description":"Create API keys in Listener → Settings → Developers."},"basicAuth":{"type":"http","scheme":"basic","description":"The API key as the username, empty password (curl -u lsk_…:)."},"oauth2":{"type":"oauth2","description":"Authorization code with PKCE (S256).","flows":{"authorizationCode":{"authorizationUrl":"https://api.listener.com/oauth/authorize","tokenUrl":"https://api.listener.com/oauth/token","refreshUrl":"https://api.listener.com/oauth/token","scopes":{"workspace:read":"Read everything in the workspace: shows, analytics, episodes, clusters, campaigns, reports, sponsors, library and webhooks.","workspace:write":"Make every change the API supports: campaigns, clusters, episodes, reports, profiles, refreshes and webhooks.","shows:read":"See the workspace, its shows, plan, team, subnetworks, integrations and public URLs.","shows:write":"Edit show and network public profiles and the network's default EMV rates.","analytics:read":"Read reach, timelines, rankings, platform stats, dashboard KPIs and recent content.","episodes:read":"Read episodes, episode search and transcripts.","episodes:write":"Set episode tags, episode goals and Substack download figures.","clusters:read":"Read episode clusters, cluster reports and timelines, and the cluster builder's sources and suggestions.","clusters:write":"Create, update, merge and delete clusters, add or remove posts, run AI cluster builds and review suggestions.","campaigns:read":"Read campaigns, brands, air checks and CPM insights.","campaigns:write":"Create, update and delete campaigns, slots, brand profiles and cluster links.","reports:read":"Read shared reports, report templates and report automations.","reports:write":"Publish and delete shared reports, save templates and disable automations.","sponsors:read":"Read sponsor matches, network bundle opportunities and sponsorship packages.","library:read":"Read workspace library files, run web and podcast searches and parse insertion orders.","refresh:write":"Trigger platform and cluster refreshes and file Spotify / Apple data requests.","webhooks:read":"Read webhook endpoints, deliveries and events.","webhooks:write":"Create, update, test and delete webhook endpoints.","offline_access":"Keep access after the session ends (issues a refresh token). OAuth only."}}}}}}}