There's a new version of the HubSpot API

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Working within the HubSpot API rate limits

HubSpot's API rate limits can be found in our API Usage Guidelines. If you exceed those limits, you'll start receiving 429 error responses for any API calls you make. Those 429 responses 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.

Each API request will include the following rate limit headers in the response. NOTE: The Daily and Daily-Remaining headers are not included for requests authorized using OAuth.

Header Description
X-HubSpot-RateLimit-Daily The number of API requests that are allowed per day.
X-HubSpot-RateLimit-Daily-Remaining The number of API requests still allowed for the current day.
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.

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 let us know on our developer forums. We want to know as many details as possible about the APIs you're using, how you're using them, and which limit you're hitting.

Cache data for repeat calls

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 contact propertiesowners, or settings for a form), those settings should also be cached when possible.

Use batch APIs when possible

If you're working with contacts, you can use the Batch API to update contacts in sets, up to 100 records per call. This endpoint works with either an email address or a contact vid to identify the records, so as long as you have the email address, you wouldn't need to look up the contact in HubSpot before being able to update the record. If you're not working with time-sensitive data, group updates into a periodic batches instead of individual ones.

You can also get data for specific contact records in batches (either by email or vid) instead of pulling individual records.

If you're working with companies or deals, there are also endpoints to update multiple records in a single request:

Use smart lists and workflow starting conditions

Smart lists can automatically include contacts based on several different criteria. Instead of creating or updating a contact and then manually adding them to a list, use custom properties and smart lists so that the new or updated records are automatically added lists based on the list criteria.

Similarly, workflows can also be automatically triggered based on different starting conditions, so new or updated contacts can be automatically enrolled in workflows without updating a record and then manually enrolling the record in the workflow with a separate request.

Use webhooks to get updated data from HubSpot

If you have a HubSpot Marketing Professional or 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.