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, we will always let developers know in advance through our Changelog.

Authentication and security

For optimal security, all apps must use HubSpot’s OAuth protocol. Apps are responsible for storing time-to-live (TTL) data and refreshing user access tokens in accordance with this protocol. When an OAuth 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 using OAuth

Use API call monitoring in the app’s settings.

Integrations using API keys

Use GET /integrations/v1/limit/daily* to check how many API calls have been made for the current day and when the limit will reset. The current day is measured from midnight to midnight based on the connected account’s time zone settings

*A call to this endpoint counts against your daily API limits.

 

Required parameters Description How to use
HubSpot API key The API key for the HubSpot account you're checking API usage for. hapikey= used in the URL

 

Example GET URL:

https://api.hubapi.com/integrations/v1/limit/daily?hapikey=demo

The data returned by this endpoint will be cached for five minutes. Check the fetchStatus and collectedAt fields in the response to determine if it's from cache.

Example response:

JSON
// [
  {
    "name": "api-calls-daily",
    "usageLimit": 1000000,
    "currentUsage": 31779,
    "collectedAt": 1560189939285,
    "fetchStatus": "SUCCESS",
    "resetsAt": 1560204000000
  }
]

The resetsAt field is a Unix timestamp (in milliseconds) of the time that the limit will reset. The limit resets at midnight based on the time zone setting of the account.

Example cache response:

JSON
// [
  {
    "name": "api-calls-daily",
    "usageLimit": 1000000,
    "currentUsage": 31779,
    "collectedAt": 1560189939285,
    "fetchStatus": "CACHED",
    "resetsAt": 1560204000000
  }
]

When the response is from cache, fetchStatus will be "CACHED", and the collectedAt will be a Unix timestamp in milliseconds indicating when the cache was last updated.


Rate limits

Apps using OAuth

Apps using OAuth are only subject to a limit of 100 requests every 10 seconds (except for the Search API, as noted below in "Other Limits"). Limits related to the API Add-on don't apply.

Integrations using API keys

Integrations using API keys are subject to the daily limits below (except for the Search API, as noted below in "Other Limits"). These daily limits reset at midnight based on the connected account’s time zone settings

 

Product tier

Limits

Free and Starter

Burst: 100/10 seconds

Daily: 250,000

Professional and Enterprise

Burst: 100/10 seconds

Daily: 500,000 

API Add-on (any tier)

Burst: 120/10 seconds 

Daily: 1,000,000


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 our App Marketplace, it must stay under this 5% limit to be certified. 

the 429 response will have the following format: 

 

JSON
//Example
{
  "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: These headers are only included for requests made using an API key.

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


Note
: 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 object properties, owners, or settings for a form), those settings should also be cached when possible.

Use batch APIs when possible

If you're not working with time-sensitive data, group updates into a periodic batches instead of individual ones can be more effective. 

If you're working with CRM objects (contacts, companies, deals, etc), there are batch methods available. 

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.


Service limits

Learn more about our service limits and pricing here.


Other limits

  • You can create up to 100 apps per developer 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
  • The Search API endpoints are rate limited to four requests per second per authentication token

Related docs

Checking API usage in-app