{"uid":"cap_iIfkRWjAFGw7PKWF9ebUU","slug":"particle-pro-get-podcast-chart-slot-history-88d429b2","name":"Particle Pro: Get Podcast Chart Slot History","description":"Get chart slot history. Returns historical chart snapshots for a chart slot, ordered most-recent first.","url":"https://api.particle.pro/v1/podcasts/rankings/history","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","properties":{"limit":{"type":"integer","format":"int64","description":"Results per page"},"since":{"type":"string","description":"Lower bound on captured_at (ISO 8601). Omit for no lower bound."},"until":{"type":"string","description":"Upper bound on captured_at (ISO 8601). Omit for no upper bound."},"cursor":{"type":"string","description":"Opaque pagination cursor from previous response"},"source":{"enum":["apple","spotify"],"type":"string","description":"Ranking source platform."},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code; case-insensitive on input."},"chart_type":{"enum":["top_podcasts"],"type":"string","description":"Chart variant within the source."},"podcast_id":{"type":"string","description":"Restrict to one podcast across the chart slot's history."},"category_slug":{"type":"string","description":"Category slug. Omit for the overall chart."}}}},"additionalProperties":false}}},"responseSchema":null,"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.04","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.04/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.04","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.04","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_sCBIg6IpO8twh7bjQDoOi","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.04","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns paginated historical chart snapshots for a podcast chart slot, ordered most-recent first, filterable by source platform, country, chart type, category, and podcast.","exampleAgentPrompt":"Pull the Apple top_podcasts chart history for the US, limited to 20 results per page, from January 1 2025 to March 31 2025 — I want to see how rankings changed over that period.","exampleUseCases":[{"title":"Track podcast's rise up the charts","prompt":"Show me the Spotify top_podcasts chart history for the UK for podcast ID 'xyz123' over the past 3 months — I want to see how its ranking has changed week by week."},{"title":"Monitor category chart trends over time","prompt":"Get me the Apple top_podcasts chart history for the comedy category in the US from October 2024 to December 2024, 25 results per page."},{"title":"Cross-period chart comparison for research","prompt":"Retrieve the Spotify top_podcasts chart history for Canada going back to January 1 2024, give me 50 results at a time so I can analyze ranking trends across the whole year."}],"resultDescription":"A paginated list of historical chart snapshots ordered most-recent first, each containing chart position data, the captured_at timestamp, platform source, country, chart type, and category. A next-page cursor is included when more results are available.","failureModes":["Invalid country code returns an error or empty results","Unsupported chart_type value rejected (only 'top_podcasts' allowed)","Invalid source platform (only 'apple' or 'spotify' accepted)","Malformed ISO 8601 date strings for since/until return validation errors","Invalid pagination cursor returns an error","No data available for specified filters returns empty result set","Payment failure (x402) blocks access to the endpoint"],"whenToPreferThis":"Use this endpoint when you need historical chart ranking data for podcasts on Apple or Spotify, especially when you need to analyze trends over time, track a specific podcast's chart trajectory, or compare rankings across date ranges. Prefer this over live/current chart endpoints when retrospective analysis is the goal.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:51:29.222Z","isFirstParty":false}