Some question about the rate limit


I read the document about the rate limit But I do not understand:

  1. What is Scope by Endpoint or Category. What are they? Can you explain it?
    I see your explain here but still not clearly with me?
    (Category: all endpoints that fall into the given category are rate limited from a single allocated limit per window.
    Endpoint: each endpoint has its own distinct allocated limit per window.)
    Can you show me an example?
  2. What is per 15-minute window? Is this same the time for each block before reset the rate limit per a token?
  3. The rate limit of Writes (POST, PUT, DELETE) Category is 300. But when I send a request:
    POST /2/stats/jobs/accounts/:account_id
    It return:
    x-rate-limit-limit: 10000
    x-rate-limit-remaining: 9999
    x-rate-limit-reset: 1508732364
    x-response-time: 58
    Can you explain me the reason why?


Thanks for the question, @erv_jackie, and for looking into some of the documentation.

The 15-minute window is endpoint-specific and depends on the time that the first request* was made. Let’s use GET accounts as an example. When I make the first request, the response headers provide the following information:

-> "x-rate-limit-limit: 2000"
-> "x-rate-limit-remaining: 1999"
-> "x-rate-limit-reset: 1509684755"

The x-rate-limit-reset value corresponds to 2017-11-03T04:52:35+00:00. Also notice that I’ve made one request, so the number remaining is 1999. When I make the second request, I get the following:

-> "x-rate-limit-limit: 2000"
-> "x-rate-limit-remaining: 1998"
-> "x-rate-limit-reset: 1509684755"

The x-rate-limit-reset value is the same. If I make a request to the GET accounts/:account_id/campaigns endpoint, for example, remaining would be 1999 and reset would be a different value.

Back to GET accounts. After 2017-11-03T04:52:35+00:00, the 15-minute window will reset.

You’re right that writes are typically given 300 requests per 15-minute window. However, even though creating an asynchronous analytics job is POST request, it’s not actually a write. Instead, the POST stats/jobs/accounts/:account_id endpoint is limited in the number of concurrent (PROCESSING) jobs that could be running at any given time, which is set to 100.

We’ll do an audit of our endpoint and ensure the Rate Limiting documentation is up to date and clear.

Thanks again for asking these questions. If you need further clarification, please let us know.

* The first request corresponds to the first request within a given 15-minute window.


Thank you for your detail answer, @juanshishido. I want to ask you another question.

  1. I see in the document has mentioned about the Category scope and Endpoint scope. Are they related to the number of rate limit or not?
  2. Does the value of rate limit per 15-minute window apply for an user (an access token)? It mean, this rate limit is applied for all accounts (get by of that user (access token). Is it correct?
    Because I read in document that “Each user token has its own distinct rate limits, even when accessing multiple advertiser accounts.” -


Good follow up questions, @erv_jackie.

  1. We’ll need to audit our endpoints to determine how we currently scope by category.
  2. Yes, that’s correct. Rate-limiting happens at the token level.


Thank you very much for your answer!