{"uid":"cap_KVfSYuYBoxS0MBEGefcYx","slug":"particle-pro-podcast-rankings-history-af2813e0","name":"Particle Pro Podcast Rankings History","description":"Get historical rankings for a podcast. Returns the historical rank entries for a podcast across one or more chart slots.","url":"https://api.particle.pro/v1/podcasts/:id/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"},"pathParams":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"Podcast slug, internal ID, or numeric iTunes ID."}}},"queryParams":{"type":"object","properties":{"limit":{"type":"integer","format":"int64","description":"Results per page"},"since":{"type":"string","description":"Lower bound on captured_at (ISO 8601)."},"until":{"type":"string","description":"Upper bound on captured_at (ISO 8601)."},"cursor":{"type":"string","description":"Opaque pagination cursor from previous response"},"source":{"enum":["apple","spotify"],"type":"string","description":"Restrict to one source."},"country":{"type":"string","description":"Restrict to one country (ISO 3166-1 alpha-2; case-insensitive on input)."},"chart_type":{"enum":["top_podcasts"],"type":"string","description":"Restrict to one chart type."},"category_slug":{"type":"string","description":"Restrict to one category slug. Omit to include every category."}}}},"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_V8fDtMtLaUfEr0w_o5IPG","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 historical chart ranking entries for a specific podcast across Apple and/or Spotify charts, filterable by date range, country, and category.","exampleAgentPrompt":"Show me the historical Apple podcast chart rankings for the podcast with ID 'serial' in the US between January 1, 2024 and June 30, 2024, limited to 50 results per page.","exampleUseCases":[{"title":"Podcast growth trend analysis","prompt":"Pull the full Apple Charts ranking history for the podcast 'conan-obrien-needs-a-friend' in the US from January 2023 through December 2023 so I can see how its chart position evolved over the year."},{"title":"Spotify ranking audit by country","prompt":"Get the Spotify historical rankings for podcast ID 1200361736 in the UK — I want to see every chart position it's held since it launched."},{"title":"Category-specific chart history check","prompt":"Show me the historical chart rankings for the podcast 'crime-junkie' restricted to the true-crime category on Apple, from March 1 to March 31, 2024, and limit results to 25 per page."}],"resultDescription":"A paginated list of historical rank entries for the specified podcast, each including the chart position, captured timestamp, source platform (Apple or Spotify), country, chart type, and category. Responses include a pagination cursor for retrieving subsequent pages of results.","failureModes":["Invalid or unknown podcast ID/slug returns a 404 not found error","Malformed ISO 8601 date strings for 'since' or 'until' result in a 400 validation error","Unsupported country code returns no results or a 400 error","Invalid source enum value (not 'apple' or 'spotify') causes a 400 bad request","Expired or invalid pagination cursor may return an error or empty results","Payment not received via x402 results in a 402 Payment Required response"],"whenToPreferThis":"Use this endpoint when you need time-series chart ranking data for a specific podcast, especially for longitudinal trend analysis, competitive benchmarking, or auditing a show's historical chart performance. Prefer this over real-time ranking endpoints when the goal is historical analysis over a date range rather than current standings.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T00:57:45.833Z","isFirstParty":false}