In your HubSpot account, there are limits to the amount of CRM data you can store. Some limits are technical, but others depend on your HubSpot subscription. You can track your usage in HubSpot or use the limits tracking API to check your limits and usage for the following data:
- Records
- Associations
- Custom properties
- Pipelines
- Calculated properties (Professional and Enterprise only)
- Association labels (Professional and Enterprise only)
- Custom objects (Enterprise only)
To view the number of records your account can store per object and how many records you're currently storing, make a GET
request to /crm/v3/limits/records
.
In the response, default objects are returned in the hubspotDefinedObjectTypes
array. For each object, the following are returned:
limit
: the number of records you can store for the object.usage
: the number of records in the account for the object.percentage
: the percentage of the total limit used.
If applicable, custom objects are returned in the customObjectTypes
object with individual object data and total custom object record limits and usage. Learn more about custom object definition limits.
Your response will look similar to the following:
//Example response
GET crm/v3/limits/records
{
"hubspotDefinedObjectTypes": [
{
"objectTypeId": "0-421",
"singularLabel": "Appointment",
"pluralLabel": "Appointments",
"limit": 500000,
"usage": 0,
"percentage": 0
},
{
"objectTypeId": "0-2",
"singularLabel": "Company",
"pluralLabel": "Companies",
"limit": 15000000,
"usage": 94,
"percentage": 0.001
},
{
"objectTypeId": "0-1",
"singularLabel": "Contact",
"pluralLabel": "Contacts",
"limit": 15000000,
"usage": 133,
"percentage": 0.001
},
{
"objectTypeId": "0-3",
"singularLabel": "Deal",
"pluralLabel": "Deals",
"limit": 15000000,
"usage": 188,
"percentage": 0.001
},
{
"objectTypeId": "0-53",
"singularLabel": "Invoice",
"pluralLabel": "Invoices",
"limit": 15000000,
"usage": 1,
"percentage": 0
},
{
"objectTypeId": "0-54",
"singularLabel": "Marketing event",
"pluralLabel": "Marketing events",
"limit": 15000000,
"usage": 2,
"percentage": 0
},
{
"objectTypeId": "0-7",
"singularLabel": "Product",
"pluralLabel": "Products",
"limit": 15000000,
"usage": 5,
"percentage": 0
},
{
"objectTypeId": "0-162",
"singularLabel": "Service",
"pluralLabel": "Services",
"limit": 500000,
"usage": 0,
"percentage": 0
},
{
"objectTypeId": "0-5",
"singularLabel": "Ticket",
"pluralLabel": "Tickets",
"limit": 15000000,
"usage": 28,
"percentage": 0
}
],
"customObjectTypes": {
"overallLimit": 1500000,
"overallUsage": 8,
"overallPercentage": 0.001,
"byObjectType": [
{
"objectTypeId": "2-19187792",
"singularLabel": "Car",
"pluralLabel": "Cars",
"usage": 1
},
{
"objectTypeId": "2-2140579",
"singularLabel": "Pet",
"pluralLabel": "Pets",
"usage": 7
}
]
}
}
In HubSpot, an individual record can only be associated to a specific number of records of the same or another object. For example, by default, a single contact record can be associated with up to 50,000 company records. You can use the association limit endpoints to check for records that are close to (80%+) or at the association limit. Learn more about technical limits for record associations.
- To check which objects have records are close to or at the association limit, make a
GET
request tocrm/v3/limits/associations/records/from
.
An object will be included in the response if it has records approaching or at the limit. If no records are close to or have reached an association limit, the response will be blank. To drill down into the specific object associations, you can use the endpoints below.
- To check the associated objects for which an object has records close to or at an association limit, make a
GET
request tocrm/v3/limits/associations/records/{fromObjectTypeId}/to
.
If records of the fromObjectType
are approaching or at the association limit for an associated object, that object will be included in the response. For example, if you make a request for companies (i.e. crm/v3/limits/associations/records/0-2/to
) and there is a company record associated with 48,000 contacts and 46,000 deals, contacts and deals will be included in the response.
- To view a sample of specific records approaching or at an association limit between two objects, make a
GET
requestcrm/v3/limits/associations/records/{fromObjectTypeId}/{toObjectTypeId}
.
In the response, the following are returned:
limit
: refers to the number of associated records each record can have.totalRecordsNearLimit
: counts the number of records using 80% or more of their association limit.totalRecordsAtLimit
: counts the number of records that have reached the limit.- If any records are near or at the limit, a sample of record
id
values will be included in thenearLimitFromRecordSamples
andatLimitFromRecordSamples
arrays.
For example, to retrieve records approaching limits for contacts to companies, you'd make a GET
request to crm/v3/limits/associations/records/0-1/0-2
. If no records are close to or at the limit, the response would look like the following:
xxxxxxxxxx
//Example response
GET crm/v3/limits/associations/records/0-1/0-2
{
"limit": 50000,
"totalRecordsNearLimit": 0,
"totalRecordsAtLimit": 0,
"nearLimitFromRecordSamples": [],
"atLimitFromRecordSamples": []
}
If your account has a Professional or Enterprise subscription, you can check the limits and usage for custom association labels.
- To track limits for all association labels in the account, make a
GET
request tocrm/v3/limits/associations/labels
. - To track limits for association labels from one object from or to all other objects, make a
GET
request tocrm/v3/limits/associations/labels
and include thefromObjectTypeId
ortoObjectTypeId
parameter. For example,crm/v3/limits/associations/labels/?fromObjectTypeId=0-1
orcrm/v3/limits/associations/labels/?toObjectTypeId=0-1
. - To track limits for association labels from one object to another specific object, make a
GET
request tocrm/v3/limits/associations/labels
and include thefromObjectTypeId
andtoObjectTypeId
parameters. For example,crm/v3/limits/associations/labels/?fromObjectTypeId=0-1&toObjectTypeId=0-2
.
In the response, the following are returned:
limit
: refers to the number of association labels you can create between the objects.usage
: the number of labels created in the account.percentage
: the percentage of the total limit used.allLabels
: an array with the names of the custom labels.
For example, to retrieve association label limits and usage for contacts to companies, you'd make a GET
request to crm/v3/limits/associations/labels/?fromObjectTypeId=0-1&toObjectTypeId=0-2
. Your response would look similar to the sample below. In this example, six out of 50 labels are created for contact to company associations.
xxxxxxxxxx
//Example response
GET crm/v3/limits/associations/labels/?fromObjectTypeId=0-1&toObjectTypeId=0-2
{
"results": [
{
"limit": 50,
"usage": 6,
"percentage": 12,
"fromObjectType": {
"objectTypeId": "0-1",
"singularLabel": "Contact",
"pluralLabel": "Contacts"
},
"toObjectType": {
"objectTypeId": "0-2",
"singularLabel": "Company",
"pluralLabel": "Companies"
},
"allLabels": [
"Billing contact",
"Chef",
"Contract worker",
"Decision maker",
"Franchise location",
"Manager"
]
}
]
}
You can view limits and usage for properties, including the number of custom properties or calculation properties you've created. The number of properties can create depends on your HubSpot subscription.
To track how many custom properties you've created overall and per object, make a GET
request to crm/v3/limits/custom-properties
.
In the response, the following are returned:
overallLimit
: the limit for custom properties across all objects.overallUsage
: the total number of custom properties in the account.overallPercentage
: the percentage of the limit used.- The
byObjectType
array includes the following for each object:limit
: the number of custom properties you can create for the object.usage
: the number of custom properties you've created for the object.percentage
: the percentage of the total limit used.
Please note: the overallLimit
and by object limit
values are distinct and separate, so the overall limit may not equal the sum of by object limits.
Your response will look similar to the following:
xxxxxxxxxx
//Example response
GET crm/v3/limits/custom-properties
{
"overallLimit": 10000,
"overallUsage": 59,
"overallPercentage": 0.59,
"byObjectType": [
{
"objectTypeId": "0-421",
"singularLabel": "Appointment",
"pluralLabel": "Appointments",
"limit": 1000,
"usage": 4,
"percentage": 0.4
},
{
"objectTypeId": "2-19187792",
"singularLabel": "Car",
"pluralLabel": "Cars",
"limit": 1000,
"usage": 1,
"percentage": 0.1
},
{
"objectTypeId": "0-2",
"singularLabel": "Company",
"pluralLabel": "Companies",
"limit": 1000,
"usage": 4,
"percentage": 0.4
},
{
"objectTypeId": "0-1",
"singularLabel": "Contact",
"pluralLabel": "Contacts",
"limit": 1000,
"usage": 58,
"percentage": 5.8
},
{
"objectTypeId": "0-3",
"singularLabel": "Deal",
"pluralLabel": "Deals",
"limit": 1000,
"usage": 15,
"percentage": 1.5
},
{
"objectTypeId": "2-19188239",
"singularLabel": "Dress",
"pluralLabel": "Dresses",
"limit": 1000,
"usage": 3,
"percentage": 0.3
},
{
"objectTypeId": "2-7282133",
"singularLabel": "Menu item",
"pluralLabel": "Menu items",
"limit": 1000,
"usage": 1,
"percentage": 0.1
},
{
"objectTypeId": "2-2140579",
"singularLabel": "Pet",
"pluralLabel": "Pets",
"limit": 1000,
"usage": 7,
"percentage": 0.7
},
{
"objectTypeId": "0-162",
"singularLabel": "Service",
"pluralLabel": "Services",
"limit": 1000,
"usage": 0,
"percentage": 0
},
{
"objectTypeId": "0-5",
"singularLabel": "Ticket",
"pluralLabel": "Tickets",
"limit": 1000,
"usage": 1,
"percentage": 0.1
}
]
}
If your account has a Professional or Enterprise subscription, you can track how many calculation properties you've created. To track calculation property usage overall and per object, make a GET
request to crm/v3/limits/calculated-properties
.
In the response, the following are returned:
overallLimit
: the limit for calculation properties across all objects.overallUsage
: the total number of calculation properties in the account.overallPercentage
: the percentage of the limit used.- The
byObjectType
array includes each object with ausage
value, which refers to the number of calculation properties you've created for the object.
Your response would look similar to the following:
xxxxxxxxxx
//Example response
GET crm/v3/limits/calculated-properties
{
"overallLimit": 200,
"overallUsage": 8,
"overallPercentage": 4,
"byObjectType": [
{
"objectTypeId": "0-421",
"singularLabel": "Appointment",
"pluralLabel": "Appointments",
"usage": 0
},
{
"objectTypeId": "2-19187792",
"singularLabel": "Car",
"pluralLabel": "Cars",
"usage": 0
},
{
"objectTypeId": "0-2",
"singularLabel": "Company",
"pluralLabel": "Companies",
"usage": 0
},
{
"objectTypeId": "0-1",
"singularLabel": "Contact",
"pluralLabel": "Contacts",
"usage": 3
},
{
"objectTypeId": "0-3",
"singularLabel": "Deal",
"pluralLabel": "Deals",
"usage": 3
},
{
"objectTypeId": "2-19188239",
"singularLabel": "Dress",
"pluralLabel": "Dresses",
"usage": 0
},
{
"objectTypeId": "2-7282133",
"singularLabel": "Menu item",
"pluralLabel": "Menu items",
"usage": 0
},
{
"objectTypeId": "2-2140579",
"singularLabel": "Pet",
"pluralLabel": "Pets",
"usage": 0
},
{
"objectTypeId": "0-162",
"singularLabel": "Service",
"pluralLabel": "Services",
"usage": 0
},
{
"objectTypeId": "0-5",
"singularLabel": "Ticket",
"pluralLabel": "Tickets",
"usage": 0
}
]
}
To view pipeline limits and usage per object, make a GET
request to crm/v3/limits/pipelines
.
Default objects with pipelines will be returned in the hubspotDefinedObjectTypes
array. For each object, the following are returned:
limit
: the number of pipelines you can create for the object.usage
: the number of pipelines created for the object.percentage
: the percentage of the total limit used.
If applicable, custom objects are returned in the customObjectTypes
object with individual object data and total custom object pipeline limits and usage. Learn more about custom object definition limits.
Your response will look similar to the following:
xxxxxxxxxx
//Example response
GET crm/v3/limits/pipelines
{
"hubspotDefinedObjectTypes": [
{
"objectTypeId": "0-421",
"singularLabel": "Appointment",
"pluralLabel": "Appointments",
"limit": 15,
"usage": 1,
"percentage": 6.667
},
{
"objectTypeId": "0-3",
"singularLabel": "Deal",
"pluralLabel": "Deals",
"limit": 100,
"usage": 5,
"percentage": 5
},
{
"objectTypeId": "0-136",
"singularLabel": "Lead",
"pluralLabel": "Leads",
"limit": 15,
"usage": 1,
"percentage": 6.667
},
{
"objectTypeId": "0-123",
"singularLabel": "Order",
"pluralLabel": "Orders",
"limit": 50,
"usage": 1,
"percentage": 2
},
{
"objectTypeId": "0-162",
"singularLabel": "Service",
"pluralLabel": "Services",
"limit": 15,
"usage": 1,
"percentage": 6.667
},
{
"objectTypeId": "0-5",
"singularLabel": "Ticket",
"pluralLabel": "Tickets",
"limit": 100,
"usage": 4,
"percentage": 4
}
],
"customObjectTypes": {
"overallLimit": 100,
"overallUsage": 3,
"overallPercentage": 3,
"byObjectType": [
{
"objectTypeId": "2-19187792",
"singularLabel": "Car",
"pluralLabel": "Cars",
"usage": 0
},
{
"objectTypeId": "2-19188239",
"singularLabel": "Dress",
"pluralLabel": "Dresses",
"usage": 1
},
{
"objectTypeId": "2-2140579",
"singularLabel": "Pet",
"pluralLabel": "Pets",
"usage": 2
}
]
}
}
If your account has a Enterprise subscription, you can view limits and usage for custom object schemas,as in the types of custom objects (e.g., Pets, Cars, etc.). If you want to view how many custom object records you can create, use the record limits endpoint instead.
To retrieve custom object limits and usage, make a GET
request to crm/v3/limits/custom-object-types
.
In the response, the following are returned:
limit
: the number of custom objects you can create.usage
: the number of custom objects you've created.percentage
: the percentage of the total limit used.
Your response would look similar to the sample below. In this example, the account has created four custom objects.
xxxxxxxxxx
//Example response
GET crm/v3/limits/custom-object-types
{
"limit": 20,
"usage": 4,
"percentage": 20
}