Skip to main content

Rate Limits

There are a few different types of rate limits on the API. The main limit that most developers will need to review is our query points. However, we also have a request limit per minute as well.

Query Cost Points

Unlike REST APIs, a GraphQL API allows you to request as little or as much information as you need. So, instead of limiting the number of requests per month you can make, the Podchaser API is limited using calculated query costs, which we refer to a query points. The total cost of a query is the sum of all the fields returned. So, the more complex a query is, the more points it will use.

You can see how many points your API keys have to use each month within the API settings page.

Cost Examples

If you used the following query to retrieve some meta data about an individual podcast, it will cost around 9 points:

query {
podcast(identifier: {id: "278981407", type: APPLE_PODCASTS}) {
id,
title,
description,
url,
rssUrl,
imageUrl,
language,
numberOfEpisodes,
}
}

Similarly, if you used the following query to request the first 10 podcasts about "Marketing" sorted by follower count to get most popular ones, it will cost around 100 points. You can learn more about searching, filter, and sorting podcasts in our searching podcasts guide.

query {
podcasts(
searchTerm: "Marketing",
first: 10,
sort: {sortBy: FOLLOWER_COUNT, direction: DESCENDING}
) {
id,
title,
description,
url,
rssUrl,
imageUrl,
language,
numberOfEpisodes,
applePodcastsId,
}
}

Cost Headers

Headers are included in the response from all queries to the API to allow you to track your points usage:

  • X-Podchaser-Points-Remaining: The number of points you have remaining (after the execution of this query, if successful)
  • X-Podchaser-Query-Cost: The number of points this query used or would have used

Failed Requests

If you query the /graphql endpoint with a query that would exceed the number of points you have remaining you will receive an HTTP 400 error and the query will not be executed. The response will still contain the Cost Headers described above.

Previewing Query Points

Before executing a query you can POST the same payload to https://api.podchaser.com/graphql/cost to determine how many points the query will use. The cost will be returned in a JSON payload as well as the standard cost headers described above.

Request Limits

We have two requests limits in place to prevent abuse and impact on our systems.

Firstly, we have a single, large request limit. It is currently set at 50 requests per 10 seconds. If you hit this limit, you will receive a 429 error and will be blocked for 1 minute. The error response will include a Retry-After header which includes when you will be able to make a new request.

Secondly, we have a points based rate limit which will prevent you from executing too many complex queries within a short period of time. This limiter utilises a leaky bucket algorithm so the more points over the maximum you go the longer you will need to wait before you can attempt your query again. The error respponse will include a Retry-After header with the number of seconds until you can successfully execute the query that put you over the limit. The actual limits and bucket leak rate may change as we tune for performance.

For most use cases, your integration should aim to reduce the number of requests per minute as much as possible by pulling as much data as you need in a single request and caching the results for a period of time within your system.