{ "openapi": "3.0.3", "info": { "title": "Podstatus API", "version": "2.0.0", "description": "Available on Professional and Network with account activation. All request examples use fictitious IDs. Dates and source semantics are documented at /docs/api." }, "servers": [ { "url": "https://podstatus.com/api/v1" } ], "paths": { "/podcasts": { "get": { "operationId": "podcasts", "x-display-name": "List podcasts", "summary": "List podcasts accessible to the account.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "podcasts:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts?per_page=25'" } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "artwork_url": { "type": "string", "nullable": true }, "apple_id": { "type": "integer", "nullable": true }, "spotify_id": { "type": "string", "nullable": true }, "ivoox_id": { "type": "integer", "nullable": true }, "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", "nullable": true, "enum": [ null, "pending", "in_progress", "completed", "failed" ] }, "available_from": { "type": "string", "nullable": true, "format": "date" }, "available_to": { "type": "string", "nullable": true, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "id": 123, "name": "The Example Podcast", "artwork_url": null, "apple_id": 123456, "spotify_id": null, "ivoox_id": null, "integrations": { "op3": { "connected": true, "sync_status": "completed", "available_from": "2026-10-01", "available_to": "2026-11-02" } } } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}": { "get": { "operationId": "podcast", "x-display-name": "Podcast details", "summary": "Podcast metadata and connected integrations.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "podcasts:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "artwork_url": { "type": "string", "nullable": true }, "apple_id": { "type": "integer", "nullable": true }, "spotify_id": { "type": "string", "nullable": true }, "ivoox_id": { "type": "integer", "nullable": true }, "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", "nullable": true, "enum": [ null, "pending", "in_progress", "completed", "failed" ] }, "available_from": { "type": "string", "nullable": true, "format": "date" }, "available_to": { "type": "string", "nullable": true, "format": "date" } }, "additionalProperties": true } }, "additionalProperties": true } }, "additionalProperties": true }, "meta": { "type": "object", "required": [], "properties": { "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": { "id": 123, "name": "The Example Podcast", "artwork_url": null, "apple_id": 123456, "spotify_id": null, "ivoox_id": null, "integrations": { "op3": { "connected": true, "sync_status": "completed", "available_from": "2026-10-01", "available_to": "2026-11-02" } } }, "meta": { "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ranking-dimensions": { "get": { "operationId": "dimensions", "x-display-name": "Chart dimensions", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/ranking-dimensions?platform=apple'" } ], "parameters": [ { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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": { "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "platform": "apple", "countries": { "ca": "Canada" }, "categories": { "26": "Podcasts" }, "category_countries": [ "ca" ], "country_aliases": {} } ], "meta": { "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/rankings/latest": { "get": { "operationId": "latest", "x-display-name": "Latest rankings", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/rankings/latest?platform=apple&country=ca&category=26'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "integer", "description": "Category ID from ranking-dimensions. Latest rankings include all supported categories when omitted.", "minimum": 0 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "status": { "type": "string", "enum": [ "ranked", "not_observed" ] } }, "additionalProperties": true } }, "meta": { "type": "object", "required": [ "timezone" ], "properties": { "timezone": { "type": "string" }, "snapshot_at": { "type": "string", "nullable": true, "format": "date-time" }, "snapshot_date": { "type": "string", "nullable": true, "format": "date" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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" ] } ] } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "podcast_id": 123, "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "position": 12, "status": "ranked" } ], "meta": { "snapshot_at": "2026-11-03T11:00:00Z", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "ivoox": { "summary": "iVoox daily chart shared with Spain", "value": { "data": [ { "podcast_id": 123, "platform": "ivoox", "country": "cl", "source_country": "es", "category": 31, "position": 12, "status": "ranked" } ], "meta": { "snapshot_date": "2026-11-02", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/rankings/overview": { "get": { "operationId": "overview", "x-display-name": "Worldwide ranking overview", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/rankings/overview'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "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", "nullable": true, "format": "date-time" }, "snapshot_date": { "type": "string", "nullable": true, "format": "date" }, "platform": { "type": "string", "enum": [ "apple", "spotify", "ivoox" ] } }, "additionalProperties": true, "oneOf": [ { "required": [ "snapshot_at" ] }, { "required": [ "snapshot_date" ] } ] } }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "podcast_id": 123, "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "position": 12, "status": "ranked" } ], "meta": { "snapshots": [ { "platform": "apple", "snapshot_at": "2026-11-03T11:00:00Z", "timezone": "UTC" } ], "timezone": "UTC", "coverage": "observed_rankings_only", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "ivoox": { "summary": "iVoox daily chart shared with Spain", "value": { "data": [ { "podcast_id": 123, "platform": "ivoox", "country": "cl", "source_country": "es", "category": 31, "position": 12, "status": "ranked" }, { "podcast_id": 123, "platform": "ivoox", "country": "pe", "source_country": "es", "category": 31, "position": 12, "status": "ranked" }, { "podcast_id": 123, "platform": "ivoox", "country": "es", "source_country": "es", "category": 31, "position": 12, "status": "ranked" } ], "meta": { "snapshots": [ { "platform": "ivoox", "snapshot_date": "2026-11-02", "timezone": "UTC" } ], "timezone": "UTC", "coverage": "observed_rankings_only", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/rankings/history": { "get": { "operationId": "history", "x-display-name": "Ranking history", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/rankings/history?platform=apple&country=ca&category=26&from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "category", "in": "query", "required": true, "schema": { "type": "integer", "description": "Category ID from ranking-dimensions. Latest rankings include all supported categories when omitted.", "minimum": 0 } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "resolution", "in": "query", "required": false, "schema": { "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" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "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", "nullable": true }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "date": "2026-11-01", "position": 15, "status": "ranked" }, { "date": "2026-11-02", "position": 12, "status": "ranked" } ], "meta": { "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "from": "2026-11-01", "to": "2026-11-02", "resolution": "day", "aggregation": "best_observed_rank", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "ivoox": { "summary": "iVoox daily chart shared with Spain", "value": { "data": [ { "date": "2026-11-01", "position": 15, "status": "ranked" }, { "date": "2026-11-02", "position": 12, "status": "ranked" } ], "meta": { "platform": "ivoox", "country": "cl", "source_country": "es", "category": 31, "from": "2026-11-01", "to": "2026-11-02", "resolution": "day", "aggregation": "stored_snapshot", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "hourly": { "summary": "Hourly data with an unobserved boundary", "value": { "data": [ { "timestamp": "2026-11-02T10:00:00Z", "position": 12, "status": "ranked" }, { "timestamp": "2026-11-02T11:00:00Z", "position": null, "status": "not_observed" } ], "meta": { "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "from": "2026-11-02T10:00:00Z", "to": "2026-11-02T11:00:00Z", "resolution": "hour", "aggregation": "stored_snapshot", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/rankings/summary": { "get": { "operationId": "summary", "x-display-name": "Ranking summary", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/rankings/summary?platform=apple&country=ca&category=26&from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "category", "in": "query", "required": true, "schema": { "type": "integer", "description": "Category ID from ranking-dimensions. Latest rankings include all supported categories when omitted.", "minimum": 0 } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "resolution", "in": "query", "required": false, "schema": { "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" ] } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Aggregation of the requested interval; monthly groups may cover partial months.", "enum": [ "period", "month" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "best_date": { "type": "string", "nullable": true }, "start_position": { "type": "integer", "nullable": true }, "end_position": { "type": "integer", "nullable": true }, "change": { "type": "integer", "nullable": true }, "observations": { "type": "integer" }, "first_available": { "type": "string", "nullable": true }, "last_available": { "type": "string", "nullable": true } }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "period": "period", "best_observed_rank": 12, "best_date": "2026-11-02", "start_position": 15, "end_position": 12, "change": 3, "observations": 2, "first_available": "2026-11-01", "last_available": "2026-11-02" } ], "meta": { "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "from": "2026-11-01", "to": "2026-11-02", "resolution": "day", "aggregation": "best_observed_rank", "timezone": "UTC", "change_definition": "start_position minus end_position; positive means improvement; null if either boundary is missing", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "ivoox": { "summary": "iVoox daily chart shared with Spain", "value": { "data": [ { "period": "period", "best_observed_rank": 12, "best_date": "2026-11-02", "start_position": 15, "end_position": 12, "change": 3, "observations": 2, "first_available": "2026-11-01", "last_available": "2026-11-02" } ], "meta": { "platform": "ivoox", "country": "cl", "source_country": "es", "category": 31, "from": "2026-11-01", "to": "2026-11-02", "resolution": "day", "aggregation": "stored_snapshot", "timezone": "UTC", "change_definition": "start_position minus end_position; positive means improvement; null if either boundary is missing", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "hourly": { "summary": "Hourly data with an unobserved boundary", "value": { "data": [ { "period": "period", "best_observed_rank": 12, "best_date": "2026-11-02T10:00:00Z", "start_position": 12, "end_position": null, "change": null, "observations": 1, "first_available": "2026-11-02T10:00:00Z", "last_available": "2026-11-02T10:00:00Z" } ], "meta": { "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "from": "2026-11-02T10:00:00Z", "to": "2026-11-02T11:00:00Z", "resolution": "hour", "aggregation": "stored_snapshot", "timezone": "UTC", "change_definition": "start_position minus end_position; positive means improvement; null if either boundary is missing", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rankings/latest": { "get": { "operationId": "batch", "x-display-name": "Batch rankings", "summary": "Latest rankings for up to five accessible podcasts in one platform and country.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "rankings:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/rankings/latest?platform=apple&country=ca&category=26&podcast_ids=123%2C124'" } ], "parameters": [ { "name": "platform", "in": "query", "required": true, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify", "ivoox" ] } }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "category", "in": "query", "required": false, "schema": { "type": "integer", "description": "Category ID from ranking-dimensions. Latest rankings include all supported categories when omitted.", "minimum": 0 } }, { "name": "podcast_ids", "in": "query", "required": true, "schema": { "type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": { "type": "integer", "minimum": 1 } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "status": { "type": "string", "enum": [ "ranked", "not_observed" ] } }, "additionalProperties": true } }, "meta": { "type": "object", "required": [ "timezone" ], "properties": { "timezone": { "type": "string" }, "snapshot_at": { "type": "string", "nullable": true, "format": "date-time" }, "snapshot_date": { "type": "string", "nullable": true, "format": "date" } }, "additionalProperties": true, "oneOf": [ { "required": [ "snapshot_at" ] }, { "required": [ "snapshot_date" ] } ] } }, "additionalProperties": true } }, "meta": { "type": "object", "required": [], "properties": { "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "podcast_id": 123, "data": [ { "podcast_id": 123, "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "position": 12, "status": "ranked" } ], "meta": { "snapshot_at": "2026-11-03T11:00:00Z", "timezone": "UTC" } }, { "podcast_id": 124, "data": [ { "podcast_id": 124, "platform": "apple", "country": "ca", "source_country": "ca", "category": 26, "position": null, "status": "not_observed" } ], "meta": { "snapshot_at": "2026-11-03T11:00:00Z", "timezone": "UTC" } } ], "meta": { "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "ivoox": { "summary": "iVoox daily chart shared with Spain", "value": { "data": [ { "podcast_id": 123, "data": [ { "podcast_id": 123, "platform": "ivoox", "country": "cl", "source_country": "es", "category": 31, "position": 12, "status": "ranked" } ], "meta": { "snapshot_date": "2026-11-02", "timezone": "UTC" } } ], "meta": { "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/downloads": { "get": { "operationId": "downloads", "x-display-name": "Downloads", "summary": "OP3 downloads by UTC day or month. Null indicates an unobserved day. Requires OP3.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "analytics:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/downloads?from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "description": "Aggregation of the requested interval; monthly groups may cover partial months.", "enum": [ "day", "month" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "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", "nullable": true }, "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", "nullable": true, "format": "date" }, "observed_total": { "type": "integer", "nullable": true }, "available_days": { "type": "integer" }, "timezone": { "type": "string" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "date": "2026-11-01", "value": 240, "status": "available" }, { "date": "2026-11-02", "value": null, "status": "not_observed" } ], "meta": { "source": "op3", "metric": "downloads", "from": "2026-11-01", "to": "2026-11-02", "latest_available_date": "2026-11-01", "observed_total": 240, "available_days": 1, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "month_available": { "summary": "Monthly group: available", "value": { "data": [ { "date": "2026-11", "value": 240, "status": "available", "from": "2026-11-01", "to": "2026-11-02", "requested_days": 2, "available_days": 2 } ], "meta": { "source": "op3", "metric": "downloads", "from": "2026-11-01", "to": "2026-11-02", "latest_available_date": "2026-11-02", "observed_total": 240, "available_days": 2, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "month_partial": { "summary": "Monthly group: partial", "value": { "data": [ { "date": "2026-11", "value": 240, "status": "partial", "from": "2026-11-01", "to": "2026-11-02", "requested_days": 2, "available_days": 1 } ], "meta": { "source": "op3", "metric": "downloads", "from": "2026-11-01", "to": "2026-11-02", "latest_available_date": "2026-11-01", "observed_total": 240, "available_days": 1, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "month_not_observed": { "summary": "Monthly group: not_observed", "value": { "data": [ { "date": "2026-11", "value": null, "status": "not_observed", "from": "2026-11-01", "to": "2026-11-02", "requested_days": 2, "available_days": 0 } ], "meta": { "source": "op3", "metric": "downloads", "from": "2026-11-01", "to": "2026-11-02", "latest_available_date": "2026-10-31", "observed_total": null, "available_days": 0, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/audience": { "get": { "operationId": "audience", "x-display-name": "Audience", "summary": "Distribution of recorded downloads, including unknown values. Percentages use the returned denominator. Requires OP3.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "analytics:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/audience?from=2026-11-01&to=2026-11-02&dimension=country'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "dimension", "in": "query", "required": true, "schema": { "type": "string", "description": "Group recorded downloads by this audience dimension.", "enum": [ "country", "region", "device", "app" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true } }, "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", "nullable": true } }, "additionalProperties": true }, { "type": "object", "required": [ "device_type", "downloads", "percentage" ], "properties": { "device_type": { "type": "string" }, "downloads": { "type": "integer" }, "percentage": { "type": "number", "nullable": true } }, "additionalProperties": true }, { "type": "object", "required": [ "agent_name", "downloads", "percentage" ], "properties": { "agent_name": { "type": "string" }, "downloads": { "type": "integer" }, "percentage": { "type": "number", "nullable": true } }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "country_code": "CA", "downloads": 240, "percentage": 100 } ], "meta": { "source": "op3", "metric": "downloads", "dimension": "country", "denominator": 240, "denominator_definition": "sum of downloads recorded for this dimension", "from": "2026-11-01", "to": "2026-11-02", "truncated": false, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "region": { "summary": "Distribution by region", "value": { "data": [ { "country_code": "CA", "region_name": "Ontario", "downloads": 240, "percentage": 100 } ], "meta": { "source": "op3", "metric": "downloads", "dimension": "region", "denominator": 240, "denominator_definition": "sum of downloads recorded for this dimension", "from": "2026-11-01", "to": "2026-11-02", "truncated": false, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "device": { "summary": "Distribution by device", "value": { "data": [ { "device_type": "mobile", "downloads": 240, "percentage": 100 } ], "meta": { "source": "op3", "metric": "downloads", "dimension": "device", "denominator": 240, "denominator_definition": "sum of downloads recorded for this dimension", "from": "2026-11-01", "to": "2026-11-02", "truncated": false, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "app": { "summary": "Distribution by app", "value": { "data": [ { "agent_name": "unknown", "downloads": 240, "percentage": 100 } ], "meta": { "source": "op3", "metric": "downloads", "dimension": "app", "denominator": 240, "denominator_definition": "sum of downloads recorded for this dimension", "from": "2026-11-01", "to": "2026-11-02", "truncated": false, "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/episodes": { "get": { "operationId": "episodes", "x-display-name": "Episodes", "summary": "Published episodes with downloads matched by exact audio URL. Unmatched or unavailable downloads are null. from/to filter downloads, published_from/to filter publication.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "analytics:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/episodes?from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Default: published (newest first). downloads sorts by descending downloads for the requested period.", "enum": [ "published", "downloads" ] } }, { "name": "published_from", "in": "query", "required": false, "schema": { "type": "string", "description": "Inclusive episode publication date in YYYY-MM-DD format." } }, { "name": "published_to", "in": "query", "required": false, "schema": { "type": "string", "description": "Inclusive episode publication date in YYYY-MM-DD format." } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true } }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "id": 789, "title": "An example episode", "published_at": "2026-11-01T08:00:00Z", "audio_url": "https://example.com/episode.mp3", "downloads": 240 } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "downloads_available": true, "from": "2026-11-01", "to": "2026-11-02", "episode_matching": "exact audio URL; unmatched episodes have null downloads", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/reviews": { "get": { "operationId": "reviews", "x-display-name": "Reviews", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "reviews:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/reviews?from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "rating", "in": "query", "required": false, "schema": { "type": "integer", "description": "Exact review rating, from 1 to 5.", "minimum": 1, "maximum": 5 } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "description": "Review source: apple, stitcher or podchaser.", "enum": [ "apple", "stitcher", "podchaser" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "title": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true }, "author": { "type": "string", "nullable": true }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "id": 321, "provider": "apple", "provider_id": 0, "country_code": "ca", "rating": 5, "title": "A helpful show", "content": "I enjoyed this episode.", "author": "Example listener", "date": "2026-11-01T12:00:00Z" } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/reviews/summary": { "get": { "operationId": "review-summary", "x-display-name": "Review statistics", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "reviews:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/reviews/summary'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "description": "Review source: apple, stitcher or podchaser.", "enum": [ "apple", "stitcher", "podchaser" ] } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true }, "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", "nullable": true }, "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", "nullable": true, "format": "date" }, "to": { "type": "string", "nullable": true, "format": "date" }, "coverage": { "type": "string", "enum": [ "stored_reviews" ] }, "timezone": { "type": "string" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": { "total_reviews": 3, "rated_reviews": 2, "average_rating": 4.5, "rating_counts": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 }, "by_provider": [ { "provider": "apple", "provider_id": 0, "total_reviews": 3, "rated_reviews": 2, "average_rating": 4.5, "rating_counts": { "1": 0, "2": 0, "3": 0, "4": 1, "5": 1 } } ] }, "meta": { "from": null, "to": null, "coverage": "stored_reviews", "timezone": "UTC", "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/keywords": { "get": { "operationId": "tracked-keywords", "x-display-name": "Tracked keywords", "summary": "List keywords the account tracks for this podcast, including those without ranking observations. Follow pagination to see all tracked keywords.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "keywords:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/keywords?per_page=25'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "keyword_id", "keyword" ], "properties": { "keyword_id": { "type": "integer" }, "keyword": { "type": "string", "nullable": true } }, "additionalProperties": true } }, "meta": { "type": "object", "required": [ "page", "per_page", "has_more" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "keyword_id": 42, "keyword": "podcast example" } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/keyword-rankings": { "get": { "operationId": "keywords", "x-display-name": "Keyword rankings", "summary": "Only keywords tracked by this account for this podcast. Paginates individual dated observations.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "keywords:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/keyword-rankings?from=2026-11-01&to=2026-11-02'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "from", "in": "query", "required": false, "schema": { "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." } }, { "name": "to", "in": "query", "required": false, "schema": { "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." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } }, { "name": "platform", "in": "query", "required": false, "schema": { "type": "string", "description": "Chart provider. Use ranking-dimensions to find supported combinations.", "enum": [ "apple", "spotify" ] } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "description": "Two-letter country code, case-insensitive. Chart support varies by platform.", "maxLength": 2, "minLength": 2 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "keyword", "keyword_id", "platform", "country", "date", "position" ], "properties": { "keyword": { "type": "string", "nullable": true }, "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" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "keyword": "podcast example", "keyword_id": 42, "platform": "apple", "country": "ca", "date": "2026-11-01", "position": 3 } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/podcasts/{id}/reports": { "get": { "operationId": "reports", "x-display-name": "List reports", "summary": "List existing reports, optionally filtered by report_id. Download links are bearer links and expire with the document.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "reports:read", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n 'https://podstatus.com/api/v1/podcasts/123/reports?per_page=25'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page number. Default: 1. The offset (page - 1) \u00d7 per_page must not exceed 10000.", "minimum": 1, "maximum": 10000 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "description": "Items per page. Default: 25.", "minimum": 1, "maximum": 50 } }, { "name": "report_id", "in": "query", "required": false, "schema": { "type": "integer", "description": "Only return this report, if it belongs to the selected podcast.", "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true, "enum": [ null, "report_generation_failed" ] }, "credit_refunded": { "type": "boolean", "nullable": true, "description": "API refund recorded; null for reports without an API request receipt." }, "expires_at": { "type": "string", "nullable": true, "format": "date-time" }, "expired": { "type": "boolean" }, "download_url": { "type": "string", "nullable": true } }, "additionalProperties": true } }, "meta": { "type": "object", "required": [ "page", "per_page", "has_more" ], "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "has_more": { "type": "boolean" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": [ { "id": 456, "podcast_id": 123, "status": "queued", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "processing": { "summary": "Report processing (fictitious download link)", "value": { "data": [ { "id": 456, "podcast_id": 123, "status": "processing", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "completed": { "summary": "Report completed (fictitious download link)", "value": { "data": [ { "id": 456, "podcast_id": 123, "status": "completed", "period_type": "monthly", "period": "2026-10", "expires_at": "2026-11-10T12:00:00Z", "expired": false, "download_url": "https://example.com/private-report", "partial_period": false, "failure_code": null, "credit_refunded": false } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "failed": { "summary": "Report failed (fictitious download link)", "value": { "data": [ { "id": 456, "podcast_id": 123, "status": "failed", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": "report_generation_failed", "credit_refunded": true } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "expired": { "summary": "Report expired (fictitious download link)", "value": { "data": [ { "id": 456, "podcast_id": 123, "status": "completed", "period_type": "monthly", "period": "2026-10", "expires_at": "2026-11-02T12:00:00Z", "expired": true, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false } ], "meta": { "page": 1, "per_page": 25, "has_more": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-report", "x-display-name": "Create report", "summary": "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.", "security": [ { "bearerAuth": [] } ], "x-required-scope": "reports:write", "x-codeSamples": [ { "lang": "Shell", "source": "curl --fail-with-body -X POST \\\n -H \"Authorization: Bearer $PODSTATUS_API_KEY\" \\\n -H 'Accept: application/json' \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: monthly-report-123-2026-10' \\\n --data '{\"period_type\":\"monthly\",\"period\":\"2026-10\",\"options\":{\"show_reviews\":true}}' \\\n 'https://podstatus.com/api/v1/podcasts/123/reports'" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "description": "Podstatus ID from GET /podcasts; this is not the Apple Podcasts ID." } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[a-zA-Z0-9._-]+$" } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true, "enum": [ null, "report_generation_failed" ] }, "credit_refunded": { "type": "boolean", "nullable": true, "description": "API refund recorded; null for reports without an API request receipt." }, "expires_at": { "type": "string", "nullable": true, "format": "date-time" }, "expired": { "type": "boolean" }, "download_url": { "type": "string", "nullable": true } }, "additionalProperties": true }, "meta": { "type": "object", "required": [ "replayed" ], "properties": { "replayed": { "type": "boolean" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "completed": { "summary": "Report completed (fictitious download link)", "value": { "data": { "id": 456, "podcast_id": 123, "status": "completed", "period_type": "monthly", "period": "2026-10", "expires_at": "2026-11-10T12:00:00Z", "expired": false, "download_url": "https://example.com/private-report", "partial_period": false, "failure_code": null, "credit_refunded": false }, "meta": { "replayed": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "failed": { "summary": "Report failed (fictitious download link)", "value": { "data": { "id": 456, "podcast_id": 123, "status": "failed", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": "report_generation_failed", "credit_refunded": true }, "meta": { "replayed": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "expired": { "summary": "Report expired (fictitious download link)", "value": { "data": { "id": 456, "podcast_id": 123, "status": "completed", "period_type": "monthly", "period": "2026-10", "expires_at": "2026-11-02T12:00:00Z", "expired": true, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false }, "meta": { "replayed": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "202": { "description": "Successful response", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "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", "nullable": true, "enum": [ null, "report_generation_failed" ] }, "credit_refunded": { "type": "boolean", "nullable": true, "description": "API refund recorded; null for reports without an API request receipt." }, "expires_at": { "type": "string", "nullable": true, "format": "date-time" }, "expired": { "type": "boolean" }, "download_url": { "type": "string", "nullable": true } }, "additionalProperties": true }, "meta": { "type": "object", "required": [ "replayed" ], "properties": { "replayed": { "type": "boolean" }, "request_id": { "type": "string", "description": "REST diagnostic ID; MCP exposes this only in the X-Request-Id HTTP header." }, "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 } } }, "examples": { "default": { "summary": "Default response", "value": { "data": { "id": 456, "podcast_id": 123, "status": "queued", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false }, "meta": { "replayed": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } }, "processing": { "summary": "Report processing (fictitious download link)", "value": { "data": { "id": 456, "podcast_id": 123, "status": "processing", "period_type": "monthly", "period": "2026-10", "expires_at": null, "expired": false, "download_url": null, "partial_period": false, "failure_code": null, "credit_refunded": false }, "meta": { "replayed": false, "request_id": "example-request-id", "usage": { "limits": { "minute": 20, "day": 1000 }, "remaining": { "minute": 19, "day": 999 }, "minute_reset_at": "2026-11-03T12:01:00Z", "daily_reset_at": "2026-11-04T00:00:00Z" } } } } } } } }, "400": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "quota_exceeded", "message": "Account request limit reached.", "details": { "window": "day", "reset_at": "2026-11-04T00:00:00Z" } }, "meta": { "request_id": "example-request-id" } } } } }, "500": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "See the documented error codes.", "headers": { "X-RateLimit-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Limit": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Remaining": { "description": "Account quota for the minute (or UTC day with Daily). Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Daily-Reset": { "description": "UTC Unix timestamp when this account quota window resets. Present after account usage is checked.", "schema": { "type": "integer", "minimum": 0 } }, "Retry-After": { "description": "Seconds before retrying, when known.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period_type", "period" ], "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 } } } }, "additionalProperties": false }, "example": { "period_type": "monthly", "period": "2026-10", "options": { "show_reviews": true } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Error": { "type": "object", "required": [ "error", "meta" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } } }, "meta": { "type": "object", "properties": { "request_id": { "type": "string" } } } } } } } }