Podstatus MCP
Connect compatible AI clients to your account's podcast rankings, reviews and analytics. The MCP server and REST API share permissions, data, caches, report credits and request limits.
Connection
- URL:
https://podstatus.com/mcp - Transport: Streamable HTTP, stateless JSON responses, POST only.
- Authentication: OAuth authorization code with PKCE (S256), or a scoped Podstatus API key.
- Access: Professional or Network, with API access enabled for the account.
- Supported protocol versions:
2025-06-18,2025-11-25,2026-07-28. - No browser cookies, query-string tokens, persistent SSE subscription or session ID on MCP requests.
Request activation from Podstatus support if your eligible account does not yet have API access.
For OAuth, sign in on Podstatus and review the permissions before allowing access. Your password stays with Podstatus. Access tokens expire after 15 minutes; clients can renew them with rotating refresh tokens for up to 30 days from authorization. Disconnect an app at any time in API settings. Revoking a connection invalidates its access and refresh tokens. Reusing a refresh token invalidates that entire connection, so clients must serialize refresh requests and reconnect after an ambiguous refresh timeout instead of replaying the old token.
For scripts and clients with fixed Bearer headers, create a dedicated expiring key
in API settings and send Authorization: Bearer YOUR_PODSTATUS_API_KEY. Never paste
keys into a chat or distribute one key across customers. OAuth tokens are accepted
only by the MCP resource; the REST API continues to use API keys.
The default is read access. Report generation also needs reports:write and spends
a report credit. Use podstatus_list_reports to check progress and keep the same
idempotency_key when retrying a report request. It also deduplicates REST requests
that use the same Idempotency-Key for the same account and payload.
ChatGPT and Claude
The Podstatus plugins package the MCP connection and a client-reporting workflow. They do not require a second server or a separate user account.
Add https://podstatus.com/mcp as a remote connection and use OAuth sign-in.
ChatGPT and Claude can discover the authorization server and register a public
client automatically; no client secret or copied API key is required. Review the
callback and permissions on Podstatus's consent screen. Default permissions are
read-only; generating paid reports requires a separate grant of reports:write.
The ChatGPT package declares OAuth with dynamic client registration (DCR).
The Claude package uses the same remote endpoint and standard OAuth discovery.
Claude Code can also connect through its /mcp sign-in flow using a registered
loopback callback. Cursor and VS Code connect the same way with their own published callbacks.
Supported native callback forms are http://localhost:PORT/callback,
http://127.0.0.1:PORT/callback and http://[::1]:PORT/callback, or the same hosts with the
root path /, with ports 1024–65535 (the root path is also accepted without a port);
only the port may change between authorizations for the same registered loopback host and path. Each authorization code remains bound to the complete URI used for that authorization, including its port.
Local MCP clients that prefer API keys can load one from an environment variable:
[mcp_servers.podstatus]
url = "https://podstatus.com/mcp"
bearer_token_env_var = "PODSTATUS_API_KEY"
OAuth support is prepared for public plugin submission. Directory publication still requires an HTTPS deployment, real-client acceptance checks and each platform's review. These packages do not imply that Podstatus is already listed in either public directory. Client availability depends on the platform and plan.
Discovery: /.well-known/oauth-protected-resource/mcp and
/.well-known/oauth-authorization-server. Send the exact resource
https://podstatus.com/mcp in both authorization and token requests.
The server accepts only authorization code and refresh grants, with public clients
(token_endpoint_auth_method: none). PKCE S256 is required. Dynamic registration
accepts the documented ChatGPT, Claude, Cursor and VS Code callbacks and bounded native loopback forms;
arbitrary external callback URLs and remote client-metadata fetching are disabled.
See the official OpenAI authentication reference, Claude connector guide and Claude Code setup.
Try a request
Use the API key from your environment. This example lists the account's podcasts:
curl https://podstatus.com/mcp \
-H "Authorization: Bearer $PODSTATUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-11-25' \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"podstatus_list_podcasts","arguments":{}}}'
Clients using 2025-06-18 or 2025-11-25 negotiate with initialize, send
notifications/initialized (HTTP 202 with an empty body), then use tools/list
and tools/call. GET requests return 405 with Allow: POST because there is no SSE stream.
Clients using 2026-07-28 do not initialize. They can call server/discover,
then tools/list and tools/call. Each request carries
params._meta["io.modelcontextprotocol/protocolVersion"] and
params._meta["io.modelcontextprotocol/clientCapabilities"]. Send matching
MCP-Protocol-Version and Mcp-Method headers, plus Mcp-Name for tool calls.
Results include resultType: "complete" and server identity in _meta.
Tool lists have ttlMs: 0 and cacheScope: "private"; do not reuse them across
accounts or changed grants. Unsupported versions or mismatched headers are rejected.
A 2026 discovery request looks like this (use the same metadata and headers on
subsequent calls, adding Mcp-Name for tools/call):
curl https://podstatus.com/mcp \
-H "Authorization: Bearer $PODSTATUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: server/discover' \
--data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'
The tool list includes only the connection's permitted
operations. Tool arguments mirror REST filters: podcast_id replaces the path ID
and idempotency_key replaces the report header. Unknown arguments are rejected.
Successful tools return the API envelope under result.structuredContent, with a
text copy under result.content. Use the source dates, missing-data flags and
meta.stale when presenting results. OP3 is required for downloads and audience;
unavailable observations must not be displayed as zero.
Limits and errors
Every admitted, authenticated MCP POST uses shared minute capacity. Initialization,
discovery, pings and notifications do not consume the daily data quota. Tool calls
consume one shared daily request, without a second debit in the REST gateway.
The reservation precedes the tool's permission and argument checks, so admitted
unknown tools and insufficient_scope errors also consume that request.
Completed internal 5xx errors release that daily reservation; minute and ingress
limits still apply. A process crash or unavailable quota database can leave the
reservation charged for that UTC day.
Professional: 20 requests/minute and 1,000/day. Network: 40/minute and 2,000/day.
Multiple keys, OAuth connections, plugins and clients do not multiply those quotas.
OAuth credential management also allows 20 new connections/account/UTC day,
240 token issuances/account/UTC hour, and 12 refreshes/connection/UTC hour.
There may be at most 20 active OAuth connections per account. These are separate
from the data request quota. A credential-quota rejection preserves the existing
credentials; respect Retry-After before retrying. Replaying an already-used refresh
token still disconnects the whole token family. Cold computations
also share the global concurrency and start-rate limits described in the API guide.
Transport/authentication failures return an HTTP error with a JSON-RPC error;
the stable API code is in error.data.code. Protocol errors use JSON-RPC codes.
Bodies and query strings are limited to 8 KiB, with at most eight JSON nesting
levels. Errors echo the JSON-RPC ID only after the body passes those checks.
Earlier rejections, including admission limits and oversized or invalid JSON,
return id: null without parsing the rejected body again.
Business errors return HTTP 200 with result.isError: true and the stable code
in result.structuredContent.error.code. Examples include podcast_not_found,
op3_not_connected and idempotency_conflict. Missing permissions return HTTP 403
with error.data.code: "insufficient_scope" and an OAuth WWW-Authenticate scope
challenge. Invalid credentials return 401. Tool-level authorization failures also
carry _meta["mcp/www_authenticate"]; they are not ordinary HTTP 200 business errors.
The administration dashboard records the logical error status even when MCP uses HTTP 200.
For HTTP 429/503, respect Retry-After. Tool errors can include error.retry_after
in seconds. Back off with jitter, do not retry indefinitely and never switch keys
to bypass limits. Every response has X-Request-Id for troubleshooting; tool
payloads omit diagnostic request IDs. Use the X-Request-Id HTTP header for private support.
Server-to-server clients normally omit Origin. Browser-origin requests are rejected
with HTTP 403 and forbidden_origin unless the operator explicitly allows that exact
origin with MCP_ALLOWED_ORIGINS. Send Content-Type: application/json; other
content types return HTTP 415 with invalid_request.
Keys should remain in a secure client credential store, never a public web page.
Enabling report generation
The read-only catalog intentionally omits podstatus_create_report. The server
instructions explain this limitation even when that tool is absent. Asking for a
report in chat does not grant a permission.
Configure the client to request its existing read scopes plus reports:write,
start a new OAuth authorization, and approve the report-credit warning on Podstatus.
Keep reports:read so the client can check the result. Refresh tokens cannot expand
permissions. After authorization, reload tools/list; the write tool becomes
available only to the new grant. The previous read-only grant stays read-only.
If the client's interface does not allow scope changes, generate the PDF in Podstatus
instead. The distributed plugins remain read-only by default; do not silently add
write access for every installation.
Consent to reports:write authorizes the capability. Separately, obtain the user's
explicit intent to spend a credit for each report. The server enforces scopes,
credits and idempotency; the assistant's confirmation behavior must be checked in
real clients and is not guaranteed by MCP annotations.
Tool reference
The catalog has 17 tools with all scopes, or 16 with all read scopes. Use
podstatus_get_chart_rankings_overview to find the countries and categories where
a podcast is observed without one request per country. Apple Podcasts, Spotify
and iVoox are supported; iVoox Chile and Peru share the Spain chart, identified
by source_country. Use podstatus_list_tracked_keywords for the keyword inventory,
and podstatus_summarize_reviews for review counts and star ratings over all stored
history or an optional date range. Read the paginated review text for thematic
analysis; aggregate stars do not establish sentiment.
Server version 2.0.0 gives tools descriptive names such as
podstatus_get_latest_chart_rankings and podstatus_summarize_chart_rankings.
Clients of the private pilot must refresh tools/list and update stored tool names.
REST paths remain under /api/v1; review provider is now a name, with the legacy
number retained in provider_id.
The following complete tool definitions are generated from the shared REST contract.
They include inputSchema, outputSchema, annotations and, when OAuth is enabled,
securitySchemes. Output schemas use JSON Schema null types and cover both successful
structuredContent and structured tool errors. Transport errors use the JSON-RPC envelope.
IDs are Podstatus podcast IDs returned by podstatus_list_podcasts.
podstatus_list_podcasts
List podcasts accessible to the account.
Required scope: podcasts:read.
{
"name": "podstatus_list_podcasts",
"title": "List podcasts",
"description": "List podcasts accessible to the account.",
"inputSchema": {
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
}
},
"required": [],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"name",
"artwork_url",
"apple_id",
"spotify_id",
"ivoox_id",
"integrations"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"artwork_url": {
"type": [
"string",
"null"
]
},
"apple_id": {
"type": [
"integer",
"null"
]
},
"spotify_id": {
"type": [
"string",
"null"
]
},
"ivoox_id": {
"type": [
"integer",
"null"
]
},
"integrations": {
"type": "object",
"required": [
"op3"
],
"properties": {
"op3": {
"type": "object",
"required": [
"connected",
"sync_status",
"available_from",
"available_to"
],
"properties": {
"connected": {
"type": "boolean"
},
"sync_status": {
"type": [
"string",
"null"
],
"enum": [
null,
"pending",
"in_progress",
"completed",
"failed"
]
},
"available_from": {
"type": [
"string",
"null"
],
"format": "date"
},
"available_to": {
"type": [
"string",
"null"
],
"format": "date"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_podcast
Podcast metadata and connected integrations.
Required scope: podcasts:read.
{
"name": "podstatus_get_podcast",
"title": "Podcast details",
"description": "Podcast metadata and connected integrations.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"name",
"artwork_url",
"apple_id",
"spotify_id",
"ivoox_id",
"integrations"
],
"properties": {
"id": {
"type": "integer"
},
"name": {
"type": [
"string",
"null"
]
},
"artwork_url": {
"type": [
"string",
"null"
]
},
"apple_id": {
"type": [
"integer",
"null"
]
},
"spotify_id": {
"type": [
"string",
"null"
]
},
"ivoox_id": {
"type": [
"integer",
"null"
]
},
"integrations": {
"type": "object",
"required": [
"op3"
],
"properties": {
"op3": {
"type": "object",
"required": [
"connected",
"sync_status",
"available_from",
"available_to"
],
"properties": {
"connected": {
"type": "boolean"
},
"sync_status": {
"type": [
"string",
"null"
],
"enum": [
null,
"pending",
"in_progress",
"completed",
"failed"
]
},
"available_from": {
"type": [
"string",
"null"
],
"format": "date"
},
"available_to": {
"type": [
"string",
"null"
],
"format": "date"
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"additionalProperties": true
},
"meta": {
"type": "object",
"required": [],
"properties": {
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_chart_dimensions
Find supported countries and categories for Apple Podcasts, Spotify and iVoox. Spotify category charts are limited to category_countries. iVoox Chile and Peru share the Spain chart, as shown in country_aliases.
Required scope: rankings:read.
{
"name": "podstatus_get_chart_dimensions",
"title": "Chart dimensions",
"description": "Find supported countries and categories for Apple Podcasts, Spotify and iVoox. Spotify category charts are limited to category_countries. iVoox Chile and Peru share the Spain chart, as shown in country_aliases.",
"inputSchema": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
}
},
"required": [],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"platform",
"countries",
"categories",
"category_countries",
"country_aliases"
],
"properties": {
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"countries": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"categories": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"category_countries": {
"type": "array",
"items": {
"type": "string"
}
},
"country_aliases": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [],
"properties": {
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_latest_chart_rankings
Get the latest chart positions of one podcast in a country, across all categories or a selected category. Supports Apple Podcasts, Spotify and iVoox. Uses the latest import marker; missing podcasts are not_observed because a marker does not prove every chart was imported successfully.
Required scope: rankings:read.
{
"name": "podstatus_get_latest_chart_rankings",
"title": "Latest rankings",
"description": "Get the latest chart positions of one podcast in a country, across all categories or a selected category. Supports Apple Podcasts, Spotify and iVoox. Uses the latest import marker; missing podcasts are not_observed because a marker does not prove every chart was imported successfully.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"category": {
"type": "integer",
"description": "Category ID from podstatus_get_chart_dimensions. Latest rankings include all supported categories when omitted.",
"minimum": 0
}
},
"required": [
"podcast_id",
"platform",
"country"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"podcast_id",
"platform",
"country",
"source_country",
"category",
"position",
"status"
],
"properties": {
"podcast_id": {
"type": "integer"
},
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string"
},
"source_country": {
"type": "string",
"description": "Country of the stored chart. iVoox cl and pe share es; these are not independent chart observations."
},
"category": {
"type": "integer"
},
"position": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ranked",
"not_observed"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"timezone"
],
"properties": {
"timezone": {
"type": "string"
},
"snapshot_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"snapshot_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true,
"oneOf": [
{
"required": [
"snapshot_at"
]
},
{
"required": [
"snapshot_date"
]
}
]
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_chart_rankings_overview
Find every country and category where a podcast has an observed ranking in the latest snapshots, in one call. Omit platform to include all connected chart platforms, or select apple, spotify or ivoox. Returns only observed positions, with snapshot dates in meta.snapshots. An absent chart does not prove the podcast is unranked. iVoox cl and pe share source_country es; do not count them as independent charts.
Required scope: rankings:read.
{
"name": "podstatus_get_chart_rankings_overview",
"title": "Worldwide ranking overview",
"description": "Find every country and category where a podcast has an observed ranking in the latest snapshots, in one call. Omit platform to include all connected chart platforms, or select apple, spotify or ivoox. Returns only observed positions, with snapshot dates in meta.snapshots. An absent chart does not prove the podcast is unranked. iVoox cl and pe share source_country es; do not count them as independent charts.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"podcast_id",
"platform",
"country",
"source_country",
"category",
"position",
"status"
],
"properties": {
"podcast_id": {
"type": "integer"
},
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string"
},
"source_country": {
"type": "string",
"description": "Country of the stored chart. iVoox cl and pe share es; these are not independent chart observations."
},
"category": {
"type": "integer"
},
"position": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ranked",
"not_observed"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"timezone",
"coverage",
"snapshots"
],
"properties": {
"timezone": {
"type": "string"
},
"coverage": {
"type": "string",
"enum": [
"observed_rankings_only"
]
},
"snapshots": {
"type": "array",
"items": {
"type": "object",
"required": [
"timezone",
"platform"
],
"properties": {
"timezone": {
"type": "string"
},
"snapshot_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"snapshot_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
}
},
"additionalProperties": true,
"oneOf": [
{
"required": [
"snapshot_at"
]
},
{
"required": [
"snapshot_date"
]
}
]
}
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_chart_ranking_history
Track a podcast chart position over a date range in a country and category. Apple supports hourly positions and daily best observed ranks; Spotify and iVoox provide daily snapshots. Missing samples are null, not_observed.
Required scope: rankings:read.
{
"name": "podstatus_get_chart_ranking_history",
"title": "Ranking history",
"description": "Track a podcast chart position over a date range in a country and category. Apple supports hourly positions and daily best observed ranks; Spotify and iVoox provide daily snapshots. Missing samples are null, not_observed.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"category": {
"type": "integer",
"description": "Category ID from podstatus_get_chart_dimensions. Latest rankings include all supported categories when omitted.",
"minimum": 0
},
"from": {
"type": "string",
"description": "YYYY-MM-DD; for resolution=hour use YYYY-MM-DDTHH:MM:SSZ and supply both bounds, aligned to whole hours. Maximum 90 daily samples or 24 elapsed hours."
},
"to": {
"type": "string",
"description": "YYYY-MM-DD; for resolution=hour use YYYY-MM-DDTHH:MM:SSZ and supply both bounds, aligned to whole hours. Maximum 90 daily samples or 24 elapsed hours."
},
"resolution": {
"type": "string",
"description": "Default: day. Hourly data is available for Apple rankings only and is retained for about the last 27 hours; older hours return not_observed. Use daily resolution for longer periods.",
"enum": [
"day",
"hour"
]
}
},
"required": [
"podcast_id",
"platform",
"country",
"category"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"date",
"position",
"status"
],
"properties": {
"date": {
"type": "string",
"format": "date"
},
"position": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ranked",
"not_observed"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"timestamp",
"position",
"status"
],
"properties": {
"timestamp": {
"type": "string",
"format": "date-time"
},
"position": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ranked",
"not_observed"
]
}
},
"additionalProperties": true
}
]
}
},
"meta": {
"type": "object",
"required": [
"platform",
"country",
"source_country",
"category",
"from",
"to",
"resolution",
"aggregation",
"timezone"
],
"properties": {
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string"
},
"source_country": {
"type": "string"
},
"category": {
"type": "integer"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"resolution": {
"type": "string",
"enum": [
"day",
"hour"
]
},
"aggregation": {
"type": "string",
"enum": [
"best_observed_rank",
"stored_snapshot"
]
},
"timezone": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_summarize_chart_rankings
Summarize a podcast chart performance over a date range: best observed rank and change from start to end, optionally by month. Positive change means improvement. Missing boundaries produce null change.
Required scope: rankings:read.
{
"name": "podstatus_summarize_chart_rankings",
"title": "Ranking summary",
"description": "Summarize a podcast chart performance over a date range: best observed rank and change from start to end, optionally by month. Positive change means improvement. Missing boundaries produce null change.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"category": {
"type": "integer",
"description": "Category ID from podstatus_get_chart_dimensions. Latest rankings include all supported categories when omitted.",
"minimum": 0
},
"from": {
"type": "string",
"description": "YYYY-MM-DD; for resolution=hour use YYYY-MM-DDTHH:MM:SSZ and supply both bounds, aligned to whole hours. Maximum 90 daily samples or 24 elapsed hours."
},
"to": {
"type": "string",
"description": "YYYY-MM-DD; for resolution=hour use YYYY-MM-DDTHH:MM:SSZ and supply both bounds, aligned to whole hours. Maximum 90 daily samples or 24 elapsed hours."
},
"resolution": {
"type": "string",
"description": "Default: day. Hourly data is available for Apple rankings only and is retained for about the last 27 hours; older hours return not_observed. Use daily resolution for longer periods.",
"enum": [
"day",
"hour"
]
},
"group_by": {
"type": "string",
"description": "Aggregation of the requested interval; monthly groups may cover partial months.",
"enum": [
"period",
"month"
]
}
},
"required": [
"podcast_id",
"platform",
"country",
"category"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"period",
"best_observed_rank",
"best_date",
"start_position",
"end_position",
"change",
"observations",
"first_available",
"last_available"
],
"properties": {
"period": {
"type": "string"
},
"best_observed_rank": {
"type": [
"integer",
"null"
]
},
"best_date": {
"type": [
"string",
"null"
]
},
"start_position": {
"type": [
"integer",
"null"
]
},
"end_position": {
"type": [
"integer",
"null"
]
},
"change": {
"type": [
"integer",
"null"
]
},
"observations": {
"type": "integer"
},
"first_available": {
"type": [
"string",
"null"
]
},
"last_available": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"platform",
"country",
"source_country",
"category",
"from",
"to",
"resolution",
"aggregation",
"timezone",
"change_definition"
],
"properties": {
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string"
},
"source_country": {
"type": "string"
},
"category": {
"type": "integer"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"resolution": {
"type": "string",
"enum": [
"day",
"hour"
]
},
"aggregation": {
"type": "string",
"enum": [
"best_observed_rank",
"stored_snapshot"
]
},
"timezone": {
"type": "string"
},
"change_definition": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_latest_chart_rankings_batch
Latest rankings for up to five accessible podcasts in one platform and country.
Required scope: rankings:read.
{
"name": "podstatus_get_latest_chart_rankings_batch",
"title": "Batch rankings",
"description": "Latest rankings for up to five accessible podcasts in one platform and country.",
"inputSchema": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"category": {
"type": "integer",
"description": "Category ID from podstatus_get_chart_dimensions. Latest rankings include all supported categories when omitted.",
"minimum": 0
},
"podcast_ids": {
"type": "array",
"minItems": 1,
"maxItems": 5,
"uniqueItems": true,
"items": {
"type": "integer",
"minimum": 1
}
}
},
"required": [
"platform",
"country",
"podcast_ids"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"podcast_id",
"data",
"meta"
],
"properties": {
"podcast_id": {
"type": "integer"
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"podcast_id",
"platform",
"country",
"source_country",
"category",
"position",
"status"
],
"properties": {
"podcast_id": {
"type": "integer"
},
"platform": {
"type": "string",
"enum": [
"apple",
"spotify",
"ivoox"
]
},
"country": {
"type": "string"
},
"source_country": {
"type": "string",
"description": "Country of the stored chart. iVoox cl and pe share es; these are not independent chart observations."
},
"category": {
"type": "integer"
},
"position": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ranked",
"not_observed"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"timezone"
],
"properties": {
"timezone": {
"type": "string"
},
"snapshot_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"snapshot_date": {
"type": [
"string",
"null"
],
"format": "date"
}
},
"additionalProperties": true,
"oneOf": [
{
"required": [
"snapshot_at"
]
},
{
"required": [
"snapshot_date"
]
}
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [],
"properties": {
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_downloads
OP3 downloads by UTC day or month. Null indicates an unobserved day. Requires OP3.
Required scope: analytics:read.
{
"name": "podstatus_get_downloads",
"title": "Downloads",
"description": "OP3 downloads by UTC day or month. Null indicates an unobserved day. Requires OP3.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"group_by": {
"type": "string",
"description": "Aggregation of the requested interval; monthly groups may cover partial months.",
"enum": [
"day",
"month"
]
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"date",
"value",
"status"
],
"properties": {
"date": {
"type": "string",
"format": "date"
},
"value": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"available",
"not_observed"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"date",
"value",
"status",
"from",
"to",
"requested_days",
"available_days"
],
"properties": {
"date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}$"
},
"value": {
"type": [
"integer",
"null"
]
},
"status": {
"type": "string",
"enum": [
"available",
"partial",
"not_observed"
]
},
"from": {
"type": "string",
"format": "date"
},
"to": {
"type": "string",
"format": "date"
},
"requested_days": {
"type": "integer"
},
"available_days": {
"type": "integer"
}
},
"additionalProperties": true
}
]
}
},
"meta": {
"type": "object",
"required": [
"from",
"to",
"source",
"metric",
"latest_available_date",
"observed_total",
"available_days",
"timezone"
],
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"op3"
]
},
"metric": {
"type": "string",
"enum": [
"downloads"
]
},
"latest_available_date": {
"type": [
"string",
"null"
],
"format": "date"
},
"observed_total": {
"type": [
"integer",
"null"
]
},
"available_days": {
"type": "integer"
},
"timezone": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_get_audience
Distribution of recorded downloads, including unknown values. Percentages use the returned denominator. Requires OP3.
Required scope: analytics:read.
{
"name": "podstatus_get_audience",
"title": "Audience",
"description": "Distribution of recorded downloads, including unknown values. Percentages use the returned denominator. Requires OP3.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"dimension": {
"type": "string",
"description": "Group recorded downloads by this audience dimension.",
"enum": [
"country",
"region",
"device",
"app"
]
}
},
"required": [
"podcast_id",
"dimension"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"country_code",
"downloads",
"percentage"
],
"properties": {
"country_code": {
"type": "string"
},
"downloads": {
"type": "integer"
},
"percentage": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true,
"not": {
"required": [
"region_name"
]
}
},
{
"type": "object",
"required": [
"country_code",
"region_name",
"downloads",
"percentage"
],
"properties": {
"country_code": {
"type": "string"
},
"region_name": {
"type": "string"
},
"downloads": {
"type": "integer"
},
"percentage": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"device_type",
"downloads",
"percentage"
],
"properties": {
"device_type": {
"type": "string"
},
"downloads": {
"type": "integer"
},
"percentage": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
},
{
"type": "object",
"required": [
"agent_name",
"downloads",
"percentage"
],
"properties": {
"agent_name": {
"type": "string"
},
"downloads": {
"type": "integer"
},
"percentage": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
}
]
}
},
"meta": {
"type": "object",
"required": [
"from",
"to",
"source",
"metric",
"denominator",
"denominator_definition",
"dimension",
"truncated",
"timezone"
],
"properties": {
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"source": {
"type": "string",
"enum": [
"op3"
]
},
"metric": {
"type": "string",
"enum": [
"downloads"
]
},
"denominator": {
"type": "integer"
},
"denominator_definition": {
"type": "string"
},
"dimension": {
"type": "string",
"enum": [
"country",
"region",
"device",
"app"
]
},
"truncated": {
"type": "boolean",
"enum": [
false
],
"description": "Oversized results fail with query_too_large instead of returning truncated aggregates."
},
"timezone": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_list_episodes
Published episodes with downloads matched by exact audio URL. Unmatched or unavailable downloads are null. from/to filter downloads, published_from/to filter publication.
Required scope: analytics:read.
{
"name": "podstatus_list_episodes",
"title": "Episodes",
"description": "Published episodes with downloads matched by exact audio URL. Unmatched or unavailable downloads are null. from/to filter downloads, published_from/to filter publication.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
},
"sort": {
"type": "string",
"description": "Default: published (newest first). downloads sorts by descending downloads for the requested period.",
"enum": [
"published",
"downloads"
]
},
"published_from": {
"type": "string",
"description": "Inclusive episode publication date in YYYY-MM-DD format."
},
"published_to": {
"type": "string",
"description": "Inclusive episode publication date in YYYY-MM-DD format."
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"published_at",
"audio_url",
"downloads"
],
"properties": {
"id": {
"type": "integer"
},
"title": {
"type": "string"
},
"published_at": {
"type": "string",
"format": "date-time"
},
"audio_url": {
"type": "string"
},
"downloads": {
"type": [
"integer",
"null"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more",
"from",
"to",
"downloads_available",
"episode_matching"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"from": {
"type": "string"
},
"to": {
"type": "string"
},
"downloads_available": {
"type": "boolean"
},
"episode_matching": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_list_reviews
Read stored listener reviews filtered by date, country, rating or provider. provider is apple, stitcher or podchaser (unknown for unrecognized legacy values); provider_id retains the numeric source code. Follow pagination for review text.
Required scope: reviews:read.
{
"name": "podstatus_list_reviews",
"title": "Reviews",
"description": "Read stored listener reviews filtered by date, country, rating or provider. provider is apple, stitcher or podchaser (unknown for unrecognized legacy values); provider_id retains the numeric source code. Follow pagination for review text.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"rating": {
"type": "integer",
"description": "Exact review rating, from 1 to 5.",
"minimum": 1,
"maximum": 5
},
"provider": {
"type": "string",
"description": "Review source: apple, stitcher or podchaser.",
"enum": [
"apple",
"stitcher",
"podchaser"
]
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"provider",
"provider_id",
"country_code",
"rating",
"title",
"content",
"author",
"date"
],
"properties": {
"id": {
"type": "integer"
},
"provider": {
"type": "string",
"enum": [
"apple",
"stitcher",
"podchaser",
"unknown"
]
},
"provider_id": {
"type": "integer"
},
"country_code": {
"type": "string"
},
"rating": {
"type": [
"integer",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"author": {
"type": [
"string",
"null"
]
},
"date": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_summarize_reviews
Count stored listener reviews and summarize their star ratings, overall and by provider, without downloading every review. Omit dates for all stored history; optional from/to are inclusive and can span more than 90 days. Only ratings 1 through 5 contribute to the average. These are recorded review statistics, not the platforms total ratings or an analysis of the review text.
Required scope: reviews:read.
{
"name": "podstatus_summarize_reviews",
"title": "Review statistics",
"description": "Count stored listener reviews and summarize their star ratings, overall and by provider, without downloading every review. Omit dates for all stored history; optional from/to are inclusive and can span more than 90 days. Only ratings 1 through 5 contribute to the average. These are recorded review statistics, not the platforms total ratings or an analysis of the review text.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Omit either bound to leave that side unbounded; omit both for all stored reviews. No 90-day limit for this aggregate."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Omit either bound to leave that side unbounded; omit both for all stored reviews. No 90-day limit for this aggregate."
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
},
"provider": {
"type": "string",
"description": "Review source: apple, stitcher or podchaser.",
"enum": [
"apple",
"stitcher",
"podchaser"
]
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "object",
"required": [
"total_reviews",
"rated_reviews",
"average_rating",
"rating_counts",
"by_provider"
],
"properties": {
"total_reviews": {
"type": "integer"
},
"rated_reviews": {
"type": "integer"
},
"average_rating": {
"type": [
"number",
"null"
]
},
"rating_counts": {
"type": "object",
"required": [
"1",
"2",
"3",
"4",
"5"
],
"properties": {
"1": {
"type": "integer"
},
"2": {
"type": "integer"
},
"3": {
"type": "integer"
},
"4": {
"type": "integer"
},
"5": {
"type": "integer"
}
}
},
"by_provider": {
"type": "array",
"items": {
"type": "object",
"required": [
"provider",
"provider_id",
"total_reviews",
"rated_reviews",
"average_rating",
"rating_counts"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"apple",
"stitcher",
"podchaser",
"unknown"
]
},
"provider_id": {
"type": "integer"
},
"total_reviews": {
"type": "integer"
},
"rated_reviews": {
"type": "integer"
},
"average_rating": {
"type": [
"number",
"null"
]
},
"rating_counts": {
"type": "object",
"required": [
"1",
"2",
"3",
"4",
"5"
],
"properties": {
"1": {
"type": "integer"
},
"2": {
"type": "integer"
},
"3": {
"type": "integer"
},
"4": {
"type": "integer"
},
"5": {
"type": "integer"
}
}
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
},
"meta": {
"type": "object",
"required": [
"from",
"to",
"coverage",
"timezone"
],
"properties": {
"from": {
"type": [
"string",
"null"
],
"format": "date"
},
"to": {
"type": [
"string",
"null"
],
"format": "date"
},
"coverage": {
"type": "string",
"enum": [
"stored_reviews"
]
},
"timezone": {
"type": "string"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_list_tracked_keywords
List keywords the account tracks for this podcast, including those without ranking observations. Follow pagination to see all tracked keywords.
Required scope: keywords:read.
{
"name": "podstatus_list_tracked_keywords",
"title": "Tracked keywords",
"description": "List keywords the account tracks for this podcast, including those without ranking observations. Follow pagination to see all tracked keywords.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"keyword_id",
"keyword"
],
"properties": {
"keyword_id": {
"type": "integer"
},
"keyword": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_list_keyword_rankings
Only keywords tracked by this account for this podcast. Paginates individual dated observations.
Required scope: keywords:read.
{
"name": "podstatus_list_keyword_rankings",
"title": "Keyword rankings",
"description": "Only keywords tracked by this account for this podcast. Paginates individual dated observations.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"from": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"to": {
"type": "string",
"description": "Inclusive UTC date in YYYY-MM-DD format. Maximum 90 days. Defaults to the 30 days ending yesterday; a supplied to sets the default from."
},
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
},
"platform": {
"type": "string",
"description": "Chart provider. Use podstatus_get_chart_dimensions to find supported combinations.",
"enum": [
"apple",
"spotify"
]
},
"country": {
"type": "string",
"description": "Two-letter country code, case-insensitive. Chart support varies by platform.",
"maxLength": 2,
"minLength": 2
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"keyword",
"keyword_id",
"platform",
"country",
"date",
"position"
],
"properties": {
"keyword": {
"type": [
"string",
"null"
]
},
"keyword_id": {
"type": "integer"
},
"platform": {
"type": "string",
"enum": [
"apple",
"spotify"
]
},
"country": {
"type": "string"
},
"date": {
"type": "string",
"format": "date"
},
"position": {
"type": "integer"
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_list_reports
List existing reports, optionally filtered by report_id. Download links are bearer links and expire with the document.
Required scope: reports:read.
{
"name": "podstatus_list_reports",
"title": "List reports",
"description": "List existing reports, optionally filtered by report_id. Download links are bearer links and expire with the document.",
"inputSchema": {
"type": "object",
"properties": {
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"page": {
"type": "integer",
"description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.",
"minimum": 1,
"maximum": 10000
},
"per_page": {
"type": "integer",
"description": "Items per page. Default: 25.",
"minimum": 1,
"maximum": 50
},
"report_id": {
"type": "integer",
"description": "Only return this report, if it belongs to the selected podcast.",
"minimum": 1
}
},
"required": [
"podcast_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"podcast_id",
"status",
"period_type",
"period",
"partial_period",
"failure_code",
"credit_refunded",
"expires_at",
"expired",
"download_url"
],
"properties": {
"id": {
"type": "integer"
},
"podcast_id": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"completed",
"failed"
]
},
"period_type": {
"type": "string",
"enum": [
"monthly",
"yearly"
]
},
"period": {
"type": "string"
},
"partial_period": {
"type": "boolean",
"description": "The calendar period was unfinished when this report was requested; does not guarantee source completeness."
},
"failure_code": {
"type": [
"string",
"null"
],
"enum": [
null,
"report_generation_failed"
]
},
"credit_refunded": {
"type": [
"boolean",
"null"
],
"description": "API refund recorded; null for reports without an API request receipt."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expired": {
"type": "boolean"
},
"download_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
}
},
"meta": {
"type": "object",
"required": [
"page",
"per_page",
"has_more"
],
"properties": {
"page": {
"type": "integer"
},
"per_page": {
"type": "integer"
},
"has_more": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}
podstatus_create_report
Queue a monthly or yearly report and spend one report credit. Requires explicit user confirmation, reports:write and idempotency_key. A completed report credit cannot be undone. Replays return the original report without consuming another credit; terminal failures refund once.
Required scope: reports:write.
{
"name": "podstatus_create_report",
"title": "Create report",
"description": "Queue a monthly or yearly report and spend one report credit. Requires explicit user confirmation, reports:write and idempotency_key. A completed report credit cannot be undone. Replays return the original report without consuming another credit; terminal failures refund once.",
"inputSchema": {
"type": "object",
"required": [
"period_type",
"period",
"podcast_id",
"idempotency_key"
],
"properties": {
"period_type": {
"type": "string",
"description": "Calendar period covered by the report.",
"enum": [
"monthly",
"yearly"
]
},
"period": {
"type": "string",
"description": "YYYY-MM for monthly reports, YYYY for yearly reports. From 2019 through the current UTC period; future periods are rejected. The unfinished current period is allowed and marked partial_period."
},
"options": {
"type": "object",
"additionalProperties": false,
"properties": {
"show_reviews": {
"type": "boolean",
"default": true
},
"show_apple_rankings": {
"type": "boolean",
"default": true
},
"show_spotify_rankings": {
"type": "boolean",
"default": true
},
"show_ivoox_rankings": {
"type": "boolean",
"default": true
},
"show_podcast_activity": {
"type": "boolean",
"default": true
},
"show_competitive_analysis": {
"type": "boolean",
"default": true
},
"show_seasonality_analysis": {
"type": "boolean",
"default": true
},
"show_sentiment_analysis": {
"type": "boolean",
"default": true
},
"show_geographic_opportunities": {
"type": "boolean",
"default": false
}
}
},
"podcast_id": {
"type": "integer",
"minimum": 1,
"description": "Podstatus ID from podstatus_list_podcasts; this is not the Apple Podcasts ID."
},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[a-zA-Z0-9._-]+$",
"description": "Generate one key for each intentional user request. Reuse it with the same arguments on every retry, including after a timeout. A new key represents a new generation and may spend another credit."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"oneOf": [
{
"type": "object",
"required": [
"data",
"meta"
],
"properties": {
"data": {
"type": "object",
"required": [
"id",
"podcast_id",
"status",
"period_type",
"period",
"partial_period",
"failure_code",
"credit_refunded",
"expires_at",
"expired",
"download_url"
],
"properties": {
"id": {
"type": "integer"
},
"podcast_id": {
"type": "integer"
},
"status": {
"type": "string",
"enum": [
"queued",
"processing",
"completed",
"failed"
]
},
"period_type": {
"type": "string",
"enum": [
"monthly",
"yearly"
]
},
"period": {
"type": "string"
},
"partial_period": {
"type": "boolean",
"description": "The calendar period was unfinished when this report was requested; does not guarantee source completeness."
},
"failure_code": {
"type": [
"string",
"null"
],
"enum": [
null,
"report_generation_failed"
]
},
"credit_refunded": {
"type": [
"boolean",
"null"
],
"description": "API refund recorded; null for reports without an API request receipt."
},
"expires_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expired": {
"type": "boolean"
},
"download_url": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": true
},
"meta": {
"type": "object",
"required": [
"replayed"
],
"properties": {
"replayed": {
"type": "boolean"
},
"usage": {
"type": "object",
"required": [
"remaining",
"limits",
"minute_reset_at",
"daily_reset_at"
],
"properties": {
"remaining": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"limits": {
"type": "object",
"required": [
"minute",
"day"
],
"properties": {
"minute": {
"type": "integer",
"minimum": 0
},
"day": {
"type": "integer",
"minimum": 0
}
},
"additionalProperties": true
},
"minute_reset_at": {
"type": "string",
"format": "date-time"
},
"daily_reset_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"cache_hit": {
"type": "boolean"
},
"stale": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
{
"type": "object",
"required": [
"error",
"meta"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"details",
"status"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
},
"status": {
"type": "integer"
},
"retry_after": {
"type": "integer",
"minimum": 0
}
}
},
"meta": {
"type": "object"
}
}
}
]
},
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": true,
"openWorldHint": false
}
}