# 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](mailto:podstatus@tenorsoftware.com) 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](/settings/api). 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: ```toml [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](https://developers.openai.com/plugins/build/auth), [Claude connector guide](https://claude.com/docs/connectors/building/authentication) and [Claude Code setup](https://code.claude.com/docs/en/mcp). ## Try a request Use the API key from your environment. This example lists the account's podcasts: ```sh 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`): ```sh 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](/docs/api). 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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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`. ```json { "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 } } ```