From ef5068a7960f59191a9d9640908c649996b2c3d3 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:05:30 +0200 Subject: [PATCH 01/14] unrelated --- docs/hub/billing.md | 2 +- docs/hub/pro.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hub/billing.md b/docs/hub/billing.md index 02a3aef3a1..e33abf76af 100644 --- a/docs/hub/billing.md +++ b/docs/hub/billing.md @@ -31,7 +31,7 @@ The PRO subscription unlocks essential features for serious users, including: - Higher tier for ZeroGPU Spaces usage - Ability to create ZeroGPU Spaces and use Dev Mode - Ability to publish Social Posts and Community Blogs -- Leverage the Data Studio on private datasets +- Leverage the [Data Studio](./datasets-viewer) on private datasets - Run and schedule serverless [CPU/ GPU Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) View the full list of benefits at https://huggingface.co/pro then subscribe over at https://huggingface.co/subscribe/pro diff --git a/docs/hub/pro.md b/docs/hub/pro.md index 970ff1a656..2174438443 100644 --- a/docs/hub/pro.md +++ b/docs/hub/pro.md @@ -8,7 +8,7 @@ The PRO subscription unlocks essential features for serious users, including: - Higher tier for [ZeroGPU Spaces](./spaces-zerogpu) usage - Ability to create ZeroGPU Spaces and use [Dev Mode](./spaces-dev-mode) - Ability to publish Social Posts and Community Blogs -- Leverage the Data Studio on private datasets +- Leverage the [Data Studio](./datasets-viewer) on private datasets - Run and schedule serverless [CPU/ GPU Jobs](https://huggingface.co/docs/huggingface_hub/en/guides/jobs) View the full list of benefits at **https://huggingface.co/pro** then subscribe over at https://huggingface.co/subscribe/pro \ No newline at end of file From 0dfcc5601e008a160ac4f0fb806bac07f6458d5b Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:06:43 +0200 Subject: [PATCH 02/14] "now" is old by now cc @mishig25 --- docs/hub/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/search.md b/docs/hub/search.md index 9c38d01f6a..2cd547f37d 100644 --- a/docs/hub/search.md +++ b/docs/hub/search.md @@ -1,6 +1,6 @@ # Search -You can now easily search anything on the Hub with **Full-text search**. We index model cards, dataset cards, and Spaces app.py files. +You can easily search anything on the Hub with **Full-text search**. We index model cards, dataset cards, and Spaces app.py files. Go directly to https://huggingface.co/search or, using the search bar at the top of https://huggingface.co, you can select "Try Full-text search" to help find what you seek on the Hub across models, datasets, and Spaces: From ab5f938a76432d539b420306aa82d3260f3b8d31 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:10:50 +0200 Subject: [PATCH 03/14] First, a few links --- docs/hub/api.md | 2 ++ docs/hub/billing.md | 2 +- docs/hub/pro.md | 2 +- docs/hub/webhooks.md | 2 +- 4 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/hub/api.md b/docs/hub/api.md index ff9b11600d..e76adcadbb 100644 --- a/docs/hub/api.md +++ b/docs/hub/api.md @@ -17,6 +17,8 @@ You can also access the OpenAPI specification directly: [https://huggingface.co/ +All API calls are subject to the HF-wide [Rate limits](./rate-limits). Upgrade your account if you need elevated, large-scale access. + ## Repo listing API The following endpoints help get information about models, datasets, and Spaces stored on the Hub. diff --git a/docs/hub/billing.md b/docs/hub/billing.md index e33abf76af..3c85c0cc9a 100644 --- a/docs/hub/billing.md +++ b/docs/hub/billing.md @@ -26,7 +26,7 @@ Private repository storage above the [included storage](./storage-limits) will b The PRO subscription unlocks essential features for serious users, including: - Higher [storage capacity](./storage-limits) for public and private repositories -- Higher bandwidth and API rate limits +- Higher bandwidth and API [rate limits](./rate-limits) - Included credits for [Inference Providers](/docs/inference-providers/) - Higher tier for ZeroGPU Spaces usage - Ability to create ZeroGPU Spaces and use Dev Mode diff --git a/docs/hub/pro.md b/docs/hub/pro.md index 2174438443..f05b20a617 100644 --- a/docs/hub/pro.md +++ b/docs/hub/pro.md @@ -3,7 +3,7 @@ The PRO subscription unlocks essential features for serious users, including: - Higher [storage capacity](./storage-limits) for public and private repositories -- Higher bandwidth and API rate limits +- Higher bandwidth and API [rate limits](./rate-limits) - Included credits for [Inference Providers](/docs/inference-providers/) - Higher tier for [ZeroGPU Spaces](./spaces-zerogpu) usage - Ability to create ZeroGPU Spaces and use [Dev Mode](./spaces-dev-mode) diff --git a/docs/hub/webhooks.md b/docs/hub/webhooks.md index 70e9deffe5..cc1849be45 100644 --- a/docs/hub/webhooks.md +++ b/docs/hub/webhooks.md @@ -242,7 +242,7 @@ This can be helpful if accessing the HTTP headers of the request is complicated Each Webhook is limited to 1,000 triggers per 24 hours. You can view your usage in the Webhook settings page in the "Activity" tab. -If you need to increase the number of triggers for your Webhook, contact us at website@huggingface.co. +If you need to increase the number of triggers for your Webhook, upgrade to PRO, Team or Enterprise and contact us at website@huggingface.co. ## Developing your Webhooks From 5d94182b6698a1c9b299650ca350a3bfebf7bb43 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:25:17 +0200 Subject: [PATCH 04/14] more links + reorder --- docs/hub/_toctree.yml | 6 ++++-- docs/hub/enterprise-hub.md | 3 ++- docs/hub/index.md | 1 + 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/hub/_toctree.yml b/docs/hub/_toctree.yml index eaf761df26..515f7f35f2 100644 --- a/docs/hub/_toctree.yml +++ b/docs/hub/_toctree.yml @@ -27,10 +27,12 @@ title: Tokens Management - local: enterprise-hub-analytics title: Publisher Analytics - - local: enterprise-hub-network-security - title: Network Security - local: enterprise-hub-gating-group-collections title: Gating Group Collections + - local: enterprise-hub-network-security + title: Network Security + - local: rate-limits + title: Rate Limits - local: pro title: PRO Plan diff --git a/docs/hub/enterprise-hub.md b/docs/hub/enterprise-hub.md index 1e0d002614..c777fdec3e 100644 --- a/docs/hub/enterprise-hub.md +++ b/docs/hub/enterprise-hub.md @@ -24,7 +24,8 @@ In this section we will document the following Enterprise Hub features: - [Advanced Security](./enterprise-hub-advanced-security) - [Tokens Management](./enterprise-hub-tokens-management) - [Publisher Analytics](./enterprise-hub-analytics) -- [Network Security](./enterprise-hub-network-security) - [Gating Group Collections](./enterprise-hub-gating-group-collections) +- [Network Security](./enterprise-hub-network-security) +- [Higher Rate limits](./rate-limits) Finally, Team & Enterprise plans include 1TB of [private repository storage](./storage-limits) per seat in the subscription, i.e. if your organization has 40 members, then you have 40TB included storage for your private models and datasets. diff --git a/docs/hub/index.md b/docs/hub/index.md index 1e2bbbb285..ebed7f8d57 100644 --- a/docs/hub/index.md +++ b/docs/hub/index.md @@ -17,6 +17,7 @@ The Hugging Face Hub is a platform with over 1.7M models, 400k datasets, and 600 Advanced Security Tokens Management Network Security +Rate Limits
From 66f09844d177940df08461235efd3a4b5764ed0e Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:25:27 +0200 Subject: [PATCH 05/14] lesssgo --- docs/hub/rate-limits.md | 87 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/hub/rate-limits.md diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md new file mode 100644 index 0000000000..488aa8d26c --- /dev/null +++ b/docs/hub/rate-limits.md @@ -0,0 +1,87 @@ +# Hub Rate limits + +To protect our platform's integrity and make sure we are able to scale our service to as many AI community members as possible, we enforce rate limits on all requests made to the HF Hub. + +We define different rate limits for distinct classes of requests. We distinguish three main buckets: + +- **Hub APIs** + - e.g. model or dataset search, repo creation, user management, etc. Note: all those endpoints are documented in [Hub API Endpoints](./api). +- **Resolvers** + - They're all the URLs that contain a `/resolve/` segment in their path, which serve user-generated content from the Hub. Concretely, those are the URLs that are constructed by open source libraries (transformers, datasets, vLLM, llama.cpp, …) or AI applications (LM Studio, Jan, ollama, …) to download model/dataset files from HF. + - Because they are very heavily used by the community, and because we optimize our infrastructure to serve them with high efficiency, rate limits for Resolvers are the highest ones. +- **Pages** + - All the Web pages we host on huggingface.co. Usually Web browsing is browsing made by humans hence rate limits don't need to be as high as programmatic endpoints like the two former buckets. + +> [!TIP] +> All values are defined over 5-minute windows, which allows for some level of "burstiness" from an application or developer's point of view. + +If you, your organization, or your application need higher rate limits, we encourage you to upgrade your account to PRO, Team, or Enterprise. We prioritize support requests from PRO, Team, and Enterprise customers – see built-in limits in [Rate limit Tiers](#rate-limit-tiers). + +## Billing dashboard + +At any point in time, you can check your rate limit status on your (or your org)'s Billing page: https://huggingface.co/settings/billing + +![dashboard for rate limits](https://cdn-uploads.huggingface.co/production/uploads/5dd96eb166059660ed1ee413/0pzQQyuVG3c9tWjCqrX9Y.png) + +On the right side, you will see three gauges, one for each bucket of Rate limiting. + +Each bucket presents the number of current (last 5 minutes) requests, and the number of allowed requests based on your user account or organization plan. + +Note: You can use the context switcher to easily switch between your user account and your orgs. + +## HTTP Headers + +Whenever you or your organization hits a rate limit, you will receive a **429** `Too Many Requests` HTTP error. + +We implement the mechanism described in the IETF draft titled “RateLimit HTTP header fields for HTTP” (also known as `draft-ietf-httpapi-ratelimit-headers`). + +The goal is to define standardized HTTP headers that servers can use to advertise quota / rate-limit policies and communicate current usage / limits to clients so that they can avoid being throttled. + +Precisely, we implement the following headers: + +| Header | Purpose / Meaning | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **RateLimit-Policy** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | +| **RateLimit-Limit** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | +| **RateLimit-Remaining** | How many requests of this type you have left in the current window. | +| **RateLimit-Reset** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | + +## Rate limit Tiers + +Here are the current rate limiting values (in September '25) based on your plan: + +| Plan | API | Resolvers | Pages | +| ------------------------------- | ------ | --------- | ----- | +| Anonymous user (per IP address) | 500 \* | 3,000 \* | 100 \* | +| Free user | 1,000 \* | 5,000 \* | 200 \* | +| PRO user | 2,500 | 12,000 | 400 | +| Team organization | 3,000 | 15,000 | 400 | +| Enterprise organization | 6,000 | 30,000 | 600 | +| Enterprise Plus organization | 10,000 | 50,000 | 1,000 | +| Academia Hub organization | 2,500 | 12,000 | 400 | + +\* Subject to change over time depending on platform health 🤞 + +## What if I get rate-limited + +First, make sure you are always passing a `HF_TOKEN`, and it gets passed downstream to all libraries or applications you might be using that downloads _stuff_ from the Hub. + +This is the number one reason users get rate limited and is a very easy fix. + +If you're sure you're passing a `HF_TOKEN`, you can: +- spread out your requests over longer periods of time +- replace Hub API calls with Resolver calls, whenever possible (Resolver rate limits are much higher and much more optimized). +- upgrade to PRO, Team, or Enterprise. + +## Granular user action Rate limits + +In addition to those main classes of rate limits, we enforce limits on certain specific kinds of user actions, like: + +- repo creation +- repo commits +- discussions and comments +- moderation actions +- etc. + +We don't currently document the rate limits for those specific actions, given they tend to change over time more often. If you get quota errors, we encourage you to upgrade your account to PRO, Team, or Enterprise. +Feel free to get in touch with us via the support team. From 6ad429df76766b53a855de1e6e723082f1f88478 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:33:58 +0200 Subject: [PATCH 06/14] Tweaks --- docs/hub/rate-limits.md | 43 ++++++++++++++++++++++------------------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index 488aa8d26c..c74770d807 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -19,7 +19,7 @@ If you, your organization, or your application need higher rate limits, we encou ## Billing dashboard -At any point in time, you can check your rate limit status on your (or your org)'s Billing page: https://huggingface.co/settings/billing +At any point in time, you can check your rate limit status on your (or your org’s) Billing page: https://huggingface.co/settings/billing ![dashboard for rate limits](https://cdn-uploads.huggingface.co/production/uploads/5dd96eb166059660ed1ee413/0pzQQyuVG3c9tWjCqrX9Y.png) @@ -27,48 +27,51 @@ On the right side, you will see three gauges, one for each bucket of Rate limiti Each bucket presents the number of current (last 5 minutes) requests, and the number of allowed requests based on your user account or organization plan. +Whenever you are above the limit in the past 5 minutes (the view is updated in real-time), the bar will turn red. + Note: You can use the context switcher to easily switch between your user account and your orgs. ## HTTP Headers Whenever you or your organization hits a rate limit, you will receive a **429** `Too Many Requests` HTTP error. -We implement the mechanism described in the IETF draft titled “RateLimit HTTP header fields for HTTP” (also known as `draft-ietf-httpapi-ratelimit-headers`). +We implement the mechanism described in the [IETF draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) titled “RateLimit HTTP header fields for HTTP” (also known as `draft-ietf-httpapi-ratelimit-headers`). The goal is to define standardized HTTP headers that servers can use to advertise quota / rate-limit policies and communicate current usage / limits to clients so that they can avoid being throttled. Precisely, we implement the following headers: -| Header | Purpose / Meaning | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **RateLimit-Policy** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | -| **RateLimit-Limit** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | -| **RateLimit-Remaining** | How many requests of this type you have left in the current window. | -| **RateLimit-Reset** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | +| Header | Purpose / Meaning | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| **`RateLimit-Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | +| **`RateLimit-Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | +| **`RateLimit-Remaining`** | How many requests of this type you have left in the current window. | +| **`RateLimit-Reset`** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | ## Rate limit Tiers Here are the current rate limiting values (in September '25) based on your plan: -| Plan | API | Resolvers | Pages | -| ------------------------------- | ------ | --------- | ----- | -| Anonymous user (per IP address) | 500 \* | 3,000 \* | 100 \* | -| Free user | 1,000 \* | 5,000 \* | 200 \* | -| PRO user | 2,500 | 12,000 | 400 | -| Team organization | 3,000 | 15,000 | 400 | -| Enterprise organization | 6,000 | 30,000 | 600 | -| Enterprise Plus organization | 10,000 | 50,000 | 1,000 | -| Academia Hub organization | 2,500 | 12,000 | 400 | +| Plan | API | Resolvers | Pages | +| ------------------------------- | -------- | --------- | ------ | +| Anonymous user (per IP address) | 500 \* | 3,000 \* | 100 \* | +| Free user | 1,000 \* | 5,000 \* | 200 \* | +| PRO user | 2,500 | 12,000 | 400 | +| Team organization | 3,000 | 15,000 | 400 | +| Enterprise organization | 6,000 | 30,000 | 600 | +| Enterprise Plus organization | 10,000 | 50,000 | 1,000 | +| Academia Hub organization | 2,500 | 12,000 | 400 | -\* Subject to change over time depending on platform health 🤞 +\* Anonymous and Free users are subject to change over time depending on platform health 🤞 ## What if I get rate-limited -First, make sure you are always passing a `HF_TOKEN`, and it gets passed downstream to all libraries or applications you might be using that downloads _stuff_ from the Hub. +First, make sure you are always passing a `HF_TOKEN`, and it gets passed downstream to all libraries or applications you might be using that downloads _stuff_ from the Hub. This is the number one reason users get rate limited and is a very easy fix. If you're sure you're passing a `HF_TOKEN`, you can: + - spread out your requests over longer periods of time - replace Hub API calls with Resolver calls, whenever possible (Resolver rate limits are much higher and much more optimized). - upgrade to PRO, Team, or Enterprise. @@ -83,5 +86,5 @@ In addition to those main classes of rate limits, we enforce limits on certain s - moderation actions - etc. -We don't currently document the rate limits for those specific actions, given they tend to change over time more often. If you get quota errors, we encourage you to upgrade your account to PRO, Team, or Enterprise. +We don't currently document the rate limits for those specific actions, given they tend to change over time more often. If you get quota errors, we encourage you to upgrade your account to PRO, Team, or Enterprise. Feel free to get in touch with us via the support team. From 58c1e5ee54d2465b1bbd3d54da8113acb4d1640c Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 17:44:34 +0200 Subject: [PATCH 07/14] Ah i forgot: add a line about E+ with defined IP Range cc @Pierrci @XciD --- docs/hub/rate-limits.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index c74770d807..f6b8fcc5d2 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -52,15 +52,16 @@ Precisely, we implement the following headers: Here are the current rate limiting values (in September '25) based on your plan: -| Plan | API | Resolvers | Pages | -| ------------------------------- | -------- | --------- | ------ | -| Anonymous user (per IP address) | 500 \* | 3,000 \* | 100 \* | -| Free user | 1,000 \* | 5,000 \* | 200 \* | -| PRO user | 2,500 | 12,000 | 400 | -| Team organization | 3,000 | 15,000 | 400 | -| Enterprise organization | 6,000 | 30,000 | 600 | -| Enterprise Plus organization | 10,000 | 50,000 | 1,000 | -| Academia Hub organization | 2,500 | 12,000 | 400 | +| Plan | API | Resolvers | Pages | +| ------------------------------------------------------------------------- | -------- | --------- | ------ | +| Anonymous user (per IP address) | 500 \* | 3,000 \* | 100 \* | +| Free user | 1,000 \* | 5,000 \* | 200 \* | +| PRO user | 2,500 | 12,000 | 400 | +| Team organization | 3,000 | 15,000 | 400 | +| Enterprise organization | 6,000 | 30,000 | 600 | +| Enterprise Plus organization | 10,000 | 50,000 | 1,000 | +| Enterprise Plus organization
When Organization IP Ranges are defined | 100,000 | 500,000 | 10,000 | +| Academia Hub organization | 2,500 | 12,000 | 400 | \* Anonymous and Free users are subject to change over time depending on platform health 🤞 From ab928612ea20965bb548aca0da04e2b026adafa9 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 18:40:51 +0200 Subject: [PATCH 08/14] Apply suggestions from code review Co-authored-by: vb Co-authored-by: Lucain --- docs/hub/rate-limits.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index f6b8fcc5d2..725ea948ef 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -1,6 +1,6 @@ # Hub Rate limits -To protect our platform's integrity and make sure we are able to scale our service to as many AI community members as possible, we enforce rate limits on all requests made to the HF Hub. +To protect our platform's integrity and ensure availability to as many AI community members as possible, we enforce rate limits on all requests made to the Hugging Face Hub. We define different rate limits for distinct classes of requests. We distinguish three main buckets: @@ -8,9 +8,10 @@ We define different rate limits for distinct classes of requests. We distinguish - e.g. model or dataset search, repo creation, user management, etc. Note: all those endpoints are documented in [Hub API Endpoints](./api). - **Resolvers** - They're all the URLs that contain a `/resolve/` segment in their path, which serve user-generated content from the Hub. Concretely, those are the URLs that are constructed by open source libraries (transformers, datasets, vLLM, llama.cpp, …) or AI applications (LM Studio, Jan, ollama, …) to download model/dataset files from HF. - - Because they are very heavily used by the community, and because we optimize our infrastructure to serve them with high efficiency, rate limits for Resolvers are the highest ones. + - Resolve requests are heavily used by the community, and since we optimize our infrastructure to serve them with maximum efficiency, the rate limits for Resolvers are the highest. - **Pages** - - All the Web pages we host on huggingface.co. Usually Web browsing is browsing made by humans hence rate limits don't need to be as high as programmatic endpoints like the two former buckets. + - All the Web pages we host on huggingface.co. + - Usually Web browsing requests are made by humans, hence rate limits don't need to be as high as the above mentioned programmatic endpoints. > [!TIP] > All values are defined over 5-minute windows, which allows for some level of "burstiness" from an application or developer's point of view. @@ -19,15 +20,15 @@ If you, your organization, or your application need higher rate limits, we encou ## Billing dashboard -At any point in time, you can check your rate limit status on your (or your org’s) Billing page: https://huggingface.co/settings/billing +At any point, you can check your rate limit status on your (or your org’s) Billing page: https://huggingface.co/settings/billing ![dashboard for rate limits](https://cdn-uploads.huggingface.co/production/uploads/5dd96eb166059660ed1ee413/0pzQQyuVG3c9tWjCqrX9Y.png) -On the right side, you will see three gauges, one for each bucket of Rate limiting. +On the right side, you will see three gauges, one for each bucket of Requests. Each bucket presents the number of current (last 5 minutes) requests, and the number of allowed requests based on your user account or organization plan. -Whenever you are above the limit in the past 5 minutes (the view is updated in real-time), the bar will turn red. +Whenever you exceed the limit in the past 5 minutes (the view is updated in real-time), the bar will turn red. Note: You can use the context switcher to easily switch between your user account and your orgs. @@ -43,14 +44,14 @@ Precisely, we implement the following headers: | Header | Purpose / Meaning | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **`RateLimit-Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | -| **`RateLimit-Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | -| **`RateLimit-Remaining`** | How many requests of this type you have left in the current window. | -| **`RateLimit-Reset`** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | +| **`RateLimit‑Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | +| **`RateLimit‑Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | +| **`RateLimit‑Remaining`** | How many requests of this type you have left in the current window. | +| **`RateLimit‑Reset`** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | ## Rate limit Tiers -Here are the current rate limiting values (in September '25) based on your plan: +Here are the current rate limits (in September '25) based on your plan: | Plan | API | Resolvers | Pages | | ------------------------------------------------------------------------- | -------- | --------- | ------ | @@ -65,13 +66,15 @@ Here are the current rate limiting values (in September '25) based on your plan: \* Anonymous and Free users are subject to change over time depending on platform health 🤞 +Note: For organizations, rate limits are applied individually to each member. + ## What if I get rate-limited -First, make sure you are always passing a `HF_TOKEN`, and it gets passed downstream to all libraries or applications you might be using that downloads _stuff_ from the Hub. +First, make sure you always pass a `HF_TOKEN`, and it is passed downstream to all libraries or applications that downloads _stuff_ from the Hub. This is the number one reason users get rate limited and is a very easy fix. -If you're sure you're passing a `HF_TOKEN`, you can: +Despite passing `HF_TOKEN` if you are still rate limited, you can: - spread out your requests over longer periods of time - replace Hub API calls with Resolver calls, whenever possible (Resolver rate limits are much higher and much more optimized). From f873987ecccbdca099ff8becbcd6fe994de5e105 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Mon, 22 Sep 2025 19:21:50 +0200 Subject: [PATCH 09/14] Update docs/hub/rate-limits.md Co-authored-by: Pedro Cuenca --- docs/hub/rate-limits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index 725ea948ef..d8cc12a2b2 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -5,7 +5,7 @@ To protect our platform's integrity and ensure availability to as many AI commun We define different rate limits for distinct classes of requests. We distinguish three main buckets: - **Hub APIs** - - e.g. model or dataset search, repo creation, user management, etc. Note: all those endpoints are documented in [Hub API Endpoints](./api). + - e.g. model or dataset search, repo creation, user management, etc. All endpoints that belong to this bucket are documented in [Hub API Endpoints](./api). - **Resolvers** - They're all the URLs that contain a `/resolve/` segment in their path, which serve user-generated content from the Hub. Concretely, those are the URLs that are constructed by open source libraries (transformers, datasets, vLLM, llama.cpp, …) or AI applications (LM Studio, Jan, ollama, …) to download model/dataset files from HF. - Resolve requests are heavily used by the community, and since we optimize our infrastructure to serve them with maximum efficiency, the rate limits for Resolvers are the highest. From 83abbcd9997fd429b7fb83d16fca0a77072ee98a Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Tue, 23 Sep 2025 12:48:51 +0200 Subject: [PATCH 10/14] add this info block --- docs/hub/api.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/hub/api.md b/docs/hub/api.md index e76adcadbb..1d64032d53 100644 --- a/docs/hub/api.md +++ b/docs/hub/api.md @@ -19,6 +19,10 @@ You can also access the OpenAPI specification directly: [https://huggingface.co/ All API calls are subject to the HF-wide [Rate limits](./rate-limits). Upgrade your account if you need elevated, large-scale access. +> [!INFO] +> The rest of this page is a partial list of some of our API endpoints. But note that the exhaustive reference is our [OpenAPI documentation](https://huggingface.co/spaces/huggingface/openapi). +> It is much more complete and guaranteed to always be up-to-date. + ## Repo listing API The following endpoints help get information about models, datasets, and Spaces stored on the Hub. From 733af347f2005887137ec49ad4afcabf39224d82 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Tue, 23 Sep 2025 12:51:35 +0200 Subject: [PATCH 11/14] explicitly link to the Resolver endpoint cc @pcuenca @SBrandeis --- docs/hub/rate-limits.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index d8cc12a2b2..237329cdf8 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -8,6 +8,7 @@ We define different rate limits for distinct classes of requests. We distinguish - e.g. model or dataset search, repo creation, user management, etc. All endpoints that belong to this bucket are documented in [Hub API Endpoints](./api). - **Resolvers** - They're all the URLs that contain a `/resolve/` segment in their path, which serve user-generated content from the Hub. Concretely, those are the URLs that are constructed by open source libraries (transformers, datasets, vLLM, llama.cpp, …) or AI applications (LM Studio, Jan, ollama, …) to download model/dataset files from HF. + - Specifically, this is the ["Resolve a file" endpoint](https://huggingface.co/spaces/huggingface/openapi#tag/models/get/{namespace}/{repo}/resolve/{rev}/{path}) documented in our OpenAPI spec. - Resolve requests are heavily used by the community, and since we optimize our infrastructure to serve them with maximum efficiency, the rate limits for Resolvers are the highest. - **Pages** - All the Web pages we host on huggingface.co. From cdb96e176ff3010bd7e76922efd46f87038a657b Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Tue, 23 Sep 2025 12:52:55 +0200 Subject: [PATCH 12/14] Update docs/hub/rate-limits.md Co-authored-by: Simon Brandeis <33657802+SBrandeis@users.noreply.github.com> --- docs/hub/rate-limits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index 237329cdf8..c4c693e25f 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -46,7 +46,7 @@ Precisely, we implement the following headers: | Header | Purpose / Meaning | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **`RateLimit‑Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | -| **`RateLimit‑Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed.” | +| **`RateLimit‑Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed to perform.” | | **`RateLimit‑Remaining`** | How many requests of this type you have left in the current window. | | **`RateLimit‑Reset`** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | From 732cede30e4e315433835e03e97647daaf6d9340 Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Tue, 23 Sep 2025 12:54:13 +0200 Subject: [PATCH 13/14] Update rate-limits.md --- docs/hub/rate-limits.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index c4c693e25f..4087ba0716 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -67,11 +67,11 @@ Here are the current rate limits (in September '25) based on your plan: \* Anonymous and Free users are subject to change over time depending on platform health 🤞 -Note: For organizations, rate limits are applied individually to each member. +Note: For organizations, rate limits are applied individually to each member, not shared among members. ## What if I get rate-limited -First, make sure you always pass a `HF_TOKEN`, and it is passed downstream to all libraries or applications that downloads _stuff_ from the Hub. +First, make sure you always pass a `HF_TOKEN`, and it is passed downstream to all libraries or applications that download _stuff_ from the Hub. This is the number one reason users get rate limited and is a very easy fix. From fac03f20ce9fe6437555ab3f164ae54ba28b8a1e Mon Sep 17 00:00:00 2001 From: Julien Chaumond Date: Tue, 23 Sep 2025 12:57:55 +0200 Subject: [PATCH 14/14] Update headers spec --- docs/hub/rate-limits.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/hub/rate-limits.md b/docs/hub/rate-limits.md index 4087ba0716..c427dffcd0 100644 --- a/docs/hub/rate-limits.md +++ b/docs/hub/rate-limits.md @@ -11,7 +11,7 @@ We define different rate limits for distinct classes of requests. We distinguish - Specifically, this is the ["Resolve a file" endpoint](https://huggingface.co/spaces/huggingface/openapi#tag/models/get/{namespace}/{repo}/resolve/{rev}/{path}) documented in our OpenAPI spec. - Resolve requests are heavily used by the community, and since we optimize our infrastructure to serve them with maximum efficiency, the rate limits for Resolvers are the highest. - **Pages** - - All the Web pages we host on huggingface.co. + - All the Web pages we host on huggingface.co. - Usually Web browsing requests are made by humans, hence rate limits don't need to be as high as the above mentioned programmatic endpoints. > [!TIP] @@ -37,18 +37,23 @@ Note: You can use the context switcher to easily switch between your user accoun Whenever you or your organization hits a rate limit, you will receive a **429** `Too Many Requests` HTTP error. -We implement the mechanism described in the [IETF draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) titled “RateLimit HTTP header fields for HTTP” (also known as `draft-ietf-httpapi-ratelimit-headers`). +We implement the mechanism described in the [IETF draft (Version 9)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) titled “RateLimit HTTP header fields for HTTP” (also known as `draft-ietf-httpapi-ratelimit-headers`). The goal is to define standardized HTTP headers that servers can use to advertise quota / rate-limit policies and communicate current usage / limits to clients so that they can avoid being throttled. Precisely, we implement the following headers: -| Header | Purpose / Meaning | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| **`RateLimit‑Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | -| **`RateLimit‑Limit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed to perform.” | -| **`RateLimit‑Remaining`** | How many requests of this type you have left in the current window. | -| **`RateLimit‑Reset`** | Number of seconds until the rate limit window resets (or until quota is refreshed). Uses a “delta-seconds” format to reduce clock sync issues. | +| Header | Purpose / Meaning | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **`RateLimit`** | The total allowed rate limit for the current window. “How many requests (of this type) you’re allowed to perform.” | +| **`RateLimit-Policy`** | Carries the rate limit policy itself (e.g. “100 requests per 5 minutes”). It’s informative; shows what policy the client is subject to. | + +A set of examples is as follows: + +| Header | Example | +| ---------------------- | ----------------------------------------------------------------------------------------------------- | +| **`RateLimit`** | `"api\|pages\|resolvers";r=[remaining];t=[seconds remaining until reset]` | +| **`RateLimit-Policy`** | `"fixed window";"api\|\pages\|resolvers";q=[total allowed for window];w=[window duration in seconds]` | ## Rate limit Tiers