[metadata]
apple-mobile-web-app-title: HubSpot docs
application-name: HubSpot docs
description: Learn about the different API and developer feature limits in HubSpot.
generator: Mintlify
language: en
msapplication-TileColor: #ff4800
msapplication-config: /docs/_mintlify/favicons/hubspot/Yga26WrQoaJFAQa3/_generated/favicon/browserconfig.xml
og:description: Learn about the different API and developer feature limits in HubSpot.
og:image: https://hubspot.mintlify.app/_next/image?url=%2F_mintlify%2Fapi%2Fog%3Fdivision%3DPlatform%26appearance%3Dlight%26title%3DAPI%2Busage%2Bguidelines%2Band%2Blimits%26description%3DLearn%2Babout%2Bthe%2Bdifferent%2BAPI%2Band%2Bdeveloper%2Bfeature%2Blimits%2Bin%2BHubSpot.%26logoLight%3Dhttps%253A%252F%252Fmintcdn.com%252Fhubspot%252FCzYDAsNnXNN88BYe%252Flogo%252Flogo.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253DCzYDAsNnXNN88BYe%2526q%253D85%2526s%253Dbb0a0ea3314b4a516149fa3b933d4633%26logoDark%3Dhttps%253A%252F%252Fmintcdn.com%252Fhubspot%252FCzYDAsNnXNN88BYe%252Flogo%252Flogo.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253DCzYDAsNnXNN88BYe%2526q%253D85%2526s%253Dbb0a0ea3314b4a516149fa3b933d4633%26primaryColor%3D%2523ff4800%26lightColor%3D%2523ff4800%26backgroundLight%3D%2523ffffff%26backgroundDark%3D%2523041617&w=1200&q=100
og:image:height: 630
og:image:width: 1200
og:site_name: HubSpot docs
og:title: API usage guidelines and limits - HubSpot docs
og:type: website
og:url: https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines
twitter:card: summary_large_image
twitter:description: Learn about the different API and developer feature limits in HubSpot.
twitter:image: https://hubspot.mintlify.app/_next/image?url=%2F_mintlify%2Fapi%2Fog%3Fdivision%3DPlatform%26appearance%3Dlight%26title%3DAPI%2Busage%2Bguidelines%2Band%2Blimits%26description%3DLearn%2Babout%2Bthe%2Bdifferent%2BAPI%2Band%2Bdeveloper%2Bfeature%2Blimits%2Bin%2BHubSpot.%26logoLight%3Dhttps%253A%252F%252Fmintcdn.com%252Fhubspot%252FCzYDAsNnXNN88BYe%252Flogo%252Flogo.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253DCzYDAsNnXNN88BYe%2526q%253D85%2526s%253Dbb0a0ea3314b4a516149fa3b933d4633%26logoDark%3Dhttps%253A%252F%252Fmintcdn.com%252Fhubspot%252FCzYDAsNnXNN88BYe%252Flogo%252Flogo.svg%253Ffit%253Dmax%2526auto%253Dformat%2526n%253DCzYDAsNnXNN88BYe%2526q%253D85%2526s%253Dbb0a0ea3314b4a516149fa3b933d4633%26primaryColor%3D%2523ff4800%26lightColor%3D%2523ff4800%26backgroundLight%3D%2523ffffff%26backgroundDark%3D%2523041617&w=1200&q=100
twitter:image:height: 630
twitter:image:width: 1200
twitter:title: API usage guidelines and limits - HubSpot docs
viewport: width=device-width, initial-scale=1, viewport-fit=cover

[canonical-links]
https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines

[document-links]
/docs/llms.txt: /docs/llms.txt
API Limit Increase: https://legal.hubspot.com/hubspot-product-and-services-catalog#Addons
API Terms: https://legal.hubspot.com/hs-developer-terms
API guide: /docs/api-reference/latest/events/send-event-data/guide#limits
API limit increase add-on: https://legal.hubspot.com/hubspot-product-and-services-catalog#Addons
API limit increase: https://legal.hubspot.com/hubspot-product-and-services-catalog#Addons
Associations API: /docs/api-reference/latest/crm/associations/associate-records/guide#limits
CRM Search API: /docs/api-reference/latest/crm/search-the-crm
CRM Search API: /docs/api-reference/latest/crm/search-the-crm#limits
Changelog: https://developers.hubspot.com/changelog
Custom events: /docs/api-reference/latest/events/send-event-data/guide
Developer Changelog: https://developers.hubspot.com/changelog
GraphQL API: /docs/cms/start-building/features/data-driven-content/graphql/query-hubspot-data-using-graphql#query-complexity-and-account-limits
HubSpot Acceptable Use Policy: https://legal.hubspot.com/acceptable-use
HubSpot Marketplace: https://ecosystem.hubspot.com/marketplace/apps
HubSpot docs home page: /docs
HubSpot’s Product & Services Catalog: https://legal.hubspot.com/hubspot-product-and-services-catalog
OAuth authentication: /docs/apps/developer-platform/build-apps/authentication/overview#oauth
OAuth protocol: /docs/apps/developer-platform/build-apps/authentication/overview#oauth
OAuth: /docs/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth
Sign up: https://app.hubspot.com/signup-hubspot/crm?intent=developer
Timeline events: /docs/api-reference/legacy/crm/extensions/timeline/guide
app installed in a single account: /docs/apps/developer-platform/build-apps/app-configuration#distribution
checking API usage in legacy private apps: /docs/apps/legacy-apps/private-apps/overview
developer forums: https://community.hubspot.com/t5/HubSpot-Developer-Support/ct-p/developers
distributed: /docs/apps/developer-platform/build-apps/app-configuration#distribution
distribution: /docs/apps/developer-platform/build-apps/app-configuration#distribution
exports API: /docs/api-reference/latest/crm/exports/guide#limits
facebook: https://www.facebook.com/hubspot
here: /docs/api-reference/legacy/automation/workflows/guide
here: https://knowledge.hubspot.com/workflows/how-do-i-use-webhooks-with-hubspot-workflows
instagram: https://www.instagram.com/hubspot
legacy private apps: /docs/apps/legacy-apps/private-apps/overview
legacy public app: /docs/apps/legacy-apps/public-apps/overview
legacy public apps: /docs/apps/legacy-apps/public-apps/overview
linkedin: https://www.linkedin.com/company/hubspot
marketing single send API: /docs/api-reference/latest/marketing/transactional-emails/guide
medium: https://medium.com/@HubSpot
monitoring API usage for legacy public apps: /docs/apps/legacy-apps/public-apps/overview#monitor-app-behavior
new developer platform: /docs/apps/developer-platform/overview
private app: /docs/apps/legacy-apps/private-apps/overview
source code API: /docs/api-reference/latest/cms/source-code/guide
starting conditions: https://knowledge.hubspot.com/workflows/understand-contact-based-workflow-types
this endpoint: /docs/api-reference/latest/account/account-information/guide
time zone setting: https://knowledge.hubspot.com/account-management/change-your-language-and-region-settings
webhook subscriptions: /docs/api-reference/latest/webhooks
x: https://x.com/HubSpot
youtube: https://youtube.com/user/HubSpot

[structured-data]
{"@context":"https://schema.org","@graph":[{"@id":"https://developers.hubspot.com/#organization","@type":"Organization","logo":{"@type":"ImageObject","url":"https://mintcdn.com/hubspot/CzYDAsNnXNN88BYe/logo/logo.svg?fit=max&auto=format&n=CzYDAsNnXNN88BYe&q=85&s=bb0a0ea3314b4a516149fa3b933d4633"},"name":"HubSpot docs","url":"https://developers.hubspot.com"},{"@id":"https://developers.hubspot.com/docs#website","@type":"WebSite","name":"HubSpot docs","publisher":{"@id":"https://developers.hubspot.com/#organization"},"url":"https://developers.hubspot.com/docs"},{"@id":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#webpage","@type":"WebPage","breadcrumb":{"@id":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#breadcrumb"},"dateModified":"2026-03-30T16:37:05.000Z","description":"Learn about the different API and developer feature limits in HubSpot.","isPartOf":{"@id":"https://developers.hubspot.com/docs#website"},"name":"API usage guidelines and limits","url":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines"},{"@id":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","item":"https://developers.hubspot.com/docs/developer-tooling/platform/versioning","name":"Platform","position":1},{"@type":"ListItem","item":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines","name":"API usage guidelines and limits","position":2}]},{"@id":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#article","@type":["Article","TechArticle"],"dateModified":"2026-03-30T16:37:05.000Z","description":"Learn about the different API and developer feature limits in HubSpot.","headline":"API usage guidelines and limits","isPartOf":{"@id":"https://developers.hubspot.com/docs#website"},"mainEntityOfPage":{"@id":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines#webpage"},"name":"API usage guidelines and limits","publisher":{"@id":"https://developers.hubspot.com/#organization"},"url":"https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines"}]}

[content]
API usage guidelines and limits - HubSpot docs
Documentation Index
Fetch the complete documentation index at:
/docs/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
HubSpot docs
home page
Search...
⌘
K
Ask Assistant
Changelog
Sign up
Sign up
Search...
Navigation
Platform
API usage guidelines and limits
close
On this page
Authentication and security
Checking API usage
Apps built on version 2025.2 and 2026.03 of the developer platform
Legacy apps
Rate limits
Publicly distributed OAuth app limits
Privately distributed app limits
Exemptions
App and account limits
API-specific limits
Timeline event limits
Custom event limits
Service limits
Rate limit error responses
Address rate limit issues
Use batch APIs and cache results when possible
Use webhooks to get updated data from HubSpot
Platform
API usage guidelines and limits
Learn about the different API and developer feature limits in HubSpot.
HubSpot closely monitors usage of all APIs to ensure a quality experience for every user. All app and integration developers must comply with the
HubSpot Acceptable Use Policy
and
API Terms
. While HubSpot reserves the right to change or deprecate the APIs over time, updates will always be provided in advance through the
Developer Changelog
.
​
Authentication and security
For optimal security, all apps must use HubSpot’s
OAuth protocol
directly, or use your app’s static auth token if you’re building an
app installed in a single account
. Apps are responsible for storing time-to-live (TTL) data and refreshing user access tokens in accordance with this protocol. When an access token is generated, it will include an
expires_in
parameter indicating how long it can be used to make API calls before refreshing.
Unauthorized (401)
requests are not a valid indicator that a new access token must be retrieved.
​
Checking API usage
​
Apps built on version 2025.2 and 2026.03 of the developer platform
To view API usage for your apps built on the
new developer platform
:
In your HubSpot account, navigate to
Development
in the main navigation bar.
In the left sidebar menu, navigate to
Monitoring
>
API call usage
.
Your API usage across all your apps will be listed at the top of the page. You can also review usage for the apps you built in your specific account, along with any third-party apps you’ve installed.
​
Legacy apps
To view API usage for a legacy
private app
:
In your HubSpot account, navigate to
Development
in the main navigation bar.
In the left sidebar menu, navigate to
Legacy apps
.
Click the
name
of the private app.
On the app details page, click the
Logs
tab.
Review the API calls listed in the table. You can also use the
search bar
,
filters
, and
date pickers
to further refine the displayed API calls.
Learn more about
checking API usage in legacy private apps
.
To view API usage for a public app using OAuth:
In your HubSpot account, navigate to
Development
in the main navigation bar.
In the left sidebar menu, navigate to
Monitoring
, then select
Logs
.
At the top, select the
name
of the app.
Use the
tabs
to view different types of requests being made to or from the app. While viewing these logs, you can click an
individual request
to view more information.
Learn more about
monitoring API usage for legacy public apps
.
​
Rate limits
The number of calls your app can make is based on your account subscription in the account it’s installed in, and whether you’ve purchased the
API limit increase
.
You can keep the following general limits in mind when making requests to HubSpot’s API endpoints, however some APIs may also have more specific limits listed on their relevant API guide (e.g., the
exports API
).
The following APIs have limits that are unique from or stricter than the general limits. Refer to each associated guide for more information.
Associations API
CRM Search API
GraphQL API
​
Publicly distributed OAuth app limits
For
legacy public apps
, and apps on the latest versions of the developer platform (2025.2 and 2026.03) using
OAuth authentication
distributed
via the HubSpot marketplace, each HubSpot account that installs your app is limited to 110 requests every 10 seconds. This excludes the
CRM Search API
.
The
API limit increase add-on
does
not
increase the limits of
legacy public apps
nor apps on the latest versions of the developer platform (2025.2 and 2026.03) using
OAuth authentication
that are
distributed
via the HubSpot marketplace.
​
Privately distributed app limits
The limits in the table below apply to
legacy private apps
, as well as apps on the latest versions of the developer platform (2025.2 and 2026.03) with a
distribution
set to
private
. Note that for these privately distributed app types:
The burst limit, detailed in the
Per 10 seconds
column below, applies individually per app.
The daily limit, detailed in the
Per day
column below, is shared across all apps within the same HubSpot account.
Product Tier
Per 10 Seconds
Per Day
Privately distributed apps
(Any Hub)
Free and Starter
100 / app
250,000 / account
(Any Hub)
Professional
190 / app
625,000 / account
(Any Hub)
Enterprise
190 / app
1,000,000 / account
Privately distributed apps with
API Limit Increase
(Any Hub)
Free, Starter, Professional, and Enterprise
250 / app
1,000,000 / account on top of your base subscription, for each limit increase. You can purchase a maximum of two API limit increases.
​
Exemptions
Some APIs are exempt from the 10-second and daily limits (e.g., certain
marketing single send API
and
source code API
endpoints). However, you should note the following for the exempt APIs:
API requests that are exempt from daily or secondary limits will
not
be logged in HubSpot. If you want to store these exempted requests, you’ll need to log these requests externally.
A high number of requests may result in
5xx
errors. These can be addressed the same as you would
429
errors
.
​
App and account limits
The following limits apply for creating legacy apps, webhook subscriptions, and CRM extension settings.
You can create up to 100
legacy public apps
per developer account.
You can create up to 20
legacy private apps
per HubSpot account.
You can create up to 1,000
webhook subscriptions
per app.
You can create up to 25 CRM extension settings per
legacy public app
.
​
API-specific limits
Some features and APIs have more limits that are listed below. Additional limis for each API can also be found on an API’s associated guide (e.g., the
exports API
).
​
Timeline event limits
Timeline events
in a legacy public app are subject to the following limits:
You can create up to 750 timeline event types per public app.
You can create up to 500 properties per timeline event type.
Each serialized event instance has the following size limits:
500 bytes for the event instance ID
510 KB per property/token
1 MB in total size for the event instance
​
Custom event limits
Custom events
are subject to the following limits:
There is a limit of 500 unique event definitions per account.
There is a limit of 30 million event completions per month.
The send custom event completions endpoint supports up to 1250 requests per second.
The custom event completion batch endpoint supports batches of 500.
Consult the other custom event restrictions in the
API guide
.
​
Service limits
Learn more about service limits and pricing on
HubSpot’s Product & Services Catalog
.
​
Rate limit error responses
Any app or integration exceeding its rate limits will receive a
429
error response for all subsequent API calls. Requests resulting in an error response shouldn’t exceed 5% of your total daily requests. If you plan on listing your app in the
HubSpot Marketplace
, it must stay under this 5% limit to be certified.
The
429
response will have the following format:
{
"status"
:
"error"
,
"message"
:
"You have reached your daily limit."
,
"errorType"
:
"RATE_LIMIT"
,
"correlationId"
:
"c033cdaa-2c40-4a64-ae48-b4cec88dad24"
,
"policyName"
:
"DAILY"
,
"requestId"
:
"3d3e35b7-0dae-4b9f-a6e3-9c230cbcf8dd"
}
The
message
and
policyName
will indicate which limit you hit (either daily or secondly).
The
daily
limit resets at midnight based on your
time zone setting
.
The following table details the rate limit headers included in the response of each API request to HubSpot, subject to the exceptions listed below the table.
Header
Description
X-HubSpot-RateLimit-Daily
The number of API requests that are allowed per day. Note that this header is not included in the response to API requests authorized using
OAuth
.
X-HubSpot-RateLimit-Daily-Remaining
The number of API requests still allowed for the current day. Note that this header is not included in the response to API requests authorized using
OAuth
.
X-HubSpot-RateLimit-Interval-Milliseconds
The window of time that the
X-HubSpot-RateLimit-Max
and
X-HubSpot-RateLimit-Remaining
headers apply to.For example, a value of 10000 would be a window of 10 seconds.
X-HubSpot-RateLimit-Max
The number of requests allowed in the window specified in
X-HubSpot-RateLimit-Interval-Milliseconds
.For example, if this header had a value of 100, and the
X-HubSpot-RateLimit-Interval-Milliseconds
header was 10000, the enforced limit would be 100 requests per 10 seconds.
X-HubSpot-RateLimit-Remaining
The number of API requests still allowed for the window specified in
X-HubSpot-RateLimit-Interval-Milliseconds
.
The
X-HubSpot-RateLimit-Secondly
and
X-HubSpot-RateLimit-Secondly-Remaining
headers are still included and will still have accurate data, but the limit referenced by these headers is no longer enforced and these two headers should be considered deprecated.
Responses from the search API endpoints will
not
include any of the rate limit headers listed above.
You can also check the number of calls used during the current day using
this endpoint
.
​
Address rate limit issues
The sections below detail two possible ways you can reduce the volume of API traffic if you repeatedly hit your API request limit. If you’re running into the
TEN_SECONDLY_ROLLING
limit, you should throttle the requests that your app is making to stay under that limit. In addition to throttling the requests, or if you’re running into the daily limit, check out the suggestions below.
If you find that you’re still hitting the call limits after looking through these suggestions, please post on HubSpot’s
developer forums
. You should include as many details as possible about the APIs you’re using, how you’re using them, and which limit you’re hitting.
​
Use batch APIs and cache results when possible
If your site or app uses data from HubSpot on each page load, that data should be cached and loaded from that cache instead of being requested from the HubSpot APIs each time. If you’re making repeated calls to get settings from your account for a batch job (such as getting your object properties, owners, or settings for a form), those settings should also be cached when possible.
​
Use webhooks to get updated data from HubSpot
If you have a HubSpot Marketing Enterprise subscription, you can use webhook actions in workflows to have data for contact records sent to your system. Webhooks can be triggered as an action in any workflow, so you can use any workflow
starting conditions
as the criteria to have contact data sent to your system. More details about using webhooks can be found
here
and example webhooks data is
here
. Webhook calls made via workflows do not count towards the API rate limit.
Last modified on
March 30, 2026
Was this page helpful?
Yes
No
⌘
I
facebook
instagram
youtube
x
linkedin
medium
Assistant
Responses are generated using AI and may contain mistakes.
