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 rate-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

As the main limit is set by the query points, we only have a single, large request limit to prevent abuse. 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.

However, 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.