API usage guidelines
HubSpot closely monitors usage of our public 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 access token if you're building a private app. 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.
Private apps
To view API usage for a private app:
- In your HubSpot account, click the settings icon in the main navigation bar.
- In the left sidebar menu, navigate to Integrations > Private 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 private apps.
Public apps using OAuth
To view API usage for a public app using OAuth:
- In your developer account, navigate to Apps in the main navigation bar.
- Click the name of the app.
- In the left sidebar menu, navigate to Monitoring.
- 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.
Public apps
For OAuth apps, each HubSpot account that installs your app is limited to 110 requests every 10 seconds. This excludes the Search API, as noted in the Other Limits section below. Limits related to the API limit increase don't apply.
Private apps
The number of calls your private app can make is based on your account subscription and whether you've purchased the API limit increase:
Product Tier | Per 10 Seconds | Per Day | |
---|---|---|---|
Private Apps |
(Any Hub) Free and Starter |
100 / private app | 250,000 / account |
(Any Hub) Professional |
190 / private app | 625,000 / account | |
(Any Hub) Enterprise |
190 / private app | 1,000,000 / account | |
Private Apps with API Limit Increase |
(Any Hub) Free, Starter, Professional, and Enterprise |
250 / private 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. |
- You can create up to 100 apps per developer account.
- You can create up to 20 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 app.
- You can create up to 750 timeline event types per app.
- You can create up to 500 properties per timeline event type.
Keep the following general limits in mind when making requests to HubSpot's API endpoints. Some APIs may also have their own, more specific limits which will be listed on the API reference page under Limits.
- The search API endpoints are rate limited to five requests per second per authentication token, and 200 records per page request. Learn more about search limits.
- 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.
- Batch requests to CRM object endpoints are limited to 100 records per request. For example, you can't batch read more than 100 contacts per request.
Learn more about service limits and pricing here.
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 App Marketplace, it must stay under this 5% limit to be certified.
The 429
response will have the following format:
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 |
Please note:
- The
X-HubSpot-RateLimit-Secondly
andX-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.
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.
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.
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.
Thank you for your feedback, it means a lot to us.