> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: dff260f3-9eaf-4781-8fdd-00c9d5bc5a68
---

# Limits tracking

> Learn how to view an account's usage and limits for CRM data such as records, associations, pipelines, and properties.

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<Accordion title="Scope requirements">
  <ScopesList
    scopes={[
  'crm.objects.appointments.read',
  'crm.objects.appointments.sensitive.read.v2',
  'crm.objects.appointments.sensitive.write.v2',
  'crm.objects.appointments.write',
  'crm.objects.carts.read',
  'crm.objects.carts.write',
  'crm.objects.commercepayments.read',
  'crm.objects.commercepayments.write',
  'crm.objects.companies.highly_sensitive.read.v2',
  'crm.objects.companies.highly_sensitive.write.v2',
  'crm.objects.companies.read',
  'crm.objects.companies.sensitive.read.v2',
  'crm.objects.companies.sensitive.write.v2',
  'crm.objects.companies.write',
  'crm.objects.contacts.highly_sensitive.read.v2',
  'crm.objects.contacts.highly_sensitive.write.v2',
  'crm.objects.contacts.read',
  'crm.objects.contacts.sensitive.read.v2',
  'crm.objects.contacts.sensitive.write.v2',
  'crm.objects.contacts.write',
  'crm.objects.courses.read',
  'crm.objects.courses.write',
  'crm.objects.custom.highly_sensitive.read.v2',
  'crm.objects.custom.highly_sensitive.write.v2',
  'crm.objects.custom.read',
  'crm.objects.custom.sensitive.read.v2',
  'crm.objects.custom.sensitive.write.v2',
  'crm.objects.custom.write',
  'crm.objects.deals.highly_sensitive.read.v2',
  'crm.objects.deals.highly_sensitive.write.v2',
  'crm.objects.deals.read',
  'crm.objects.deals.sensitive.read.v2',
  'crm.objects.deals.sensitive.write.v2',
  'crm.objects.deals.write',
  'crm.objects.goals.read',
  'crm.objects.goals.write',
  'crm.objects.invoices.read',
  'crm.objects.invoices.write',
  'crm.objects.leads.read',
  'crm.objects.leads.write',
  'crm.objects.line_items.read',
  'crm.objects.line_items.write',
  'crm.objects.listings.read',
  'crm.objects.listings.write',
  'crm.objects.orders.read',
  'crm.objects.orders.write',
  'crm.objects.partner-clients.read',
  'crm.objects.partner-clients.write',
  'crm.objects.partner-services.read',
  'crm.objects.partner-services.write',
  'crm.objects.products.read',
  'crm.objects.products.write',
  'crm.objects.quotes.read',
  'crm.objects.quotes.write',
  'crm.objects.services.read',
  'crm.objects.services.write',
  'crm.objects.subscriptions.read',
  'crm.objects.subscriptions.write',
  'crm.objects.users.read',
  'crm.objects.users.write',
  'crm.schemas.custom.read',
  'e-commerce',
  'media_bridge.read',
  'tickets',
  'tickets.highly_sensitive.v2',
  'tickets.sensitive.v2'
]}
  />
</Accordion>

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](https://legal.hubspot.com/hubspot-product-and-services-catalog). You can [track your usage in HubSpot](https://knowledge.hubspot.com/data-management/track-crm-data-limits) 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)

## Retrieve record limits and usage

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/limits/2026-03/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](#retrieve-custom-object-limits-and-usage).

Your response will look similar to the following:

```json theme={null}
{
  "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
      }
    ]
  }
}
```

## Retrieve record association limits and usage

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](https://legal.hubspot.com/hubspot-product-and-services-catalog#TechnicalLimits).

* To check which objects have records that are close to or at the association limit, make a `GET` request to `crm/limits/2026-03/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 which associated object types have records approaching or at the association limit for a specific object type, make a `GET` request to `crm/limits/2026-03/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/limits/2026-03/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` request to `crm/limits/2026-03/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 the `nearLimitFromRecordSamples` and `atLimitFromRecordSamples` arrays.

For example, to retrieve records approaching limits for contacts to companies, you'd make a `GET` request to `crm/limits/2026-03/associations/records/0-1/0-2`. If no records are close to or at the limit, the response would look like the following:

```json theme={null}
{
  "limit": 50000,
  "totalRecordsNearLimit": 0,
  "totalRecordsAtLimit": 0,
  "nearLimitFromRecordSamples": [],
  "atLimitFromRecordSamples": []
}
```

## Retrieve association label limits and usage

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 to `crm/limits/2026-03/associations/labels`.
* To track limits for association labels from one object or to all other objects, make a `GET` request to `crm/limits/2026-03/associations/labels` and include the `fromObjectTypeId` or `toObjectTypeId` parameter. For example, `crm/limits/2026-03/associations/labels/?fromObjectTypeId=0-1` or `crm/limits/2026-03/associations/labels/?toObjectTypeId=0-1`.
* To track limits for association labels from one object to another specific object, make a `GET` request to `crm/limits/2026-03/associations/labels` and include the `fromObjectTypeId` and `toObjectTypeId` parameters. For example, `crm/limits/2026-03/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/limits/2026-03/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.

```json theme={null}
{
  "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"
      ]
    }
  ]
}
```

## Retrieve property limits and usage

You can view limits and usage for properties, including the number of custom properties or calculation properties you've created. The number of properties you can create depends on your [HubSpot subscription](https://legal.hubspot.com/hubspot-product-and-services-catalog).

### Custom properties

To track how many custom properties you've created overall and per object, make a `GET` request to `crm/limits/2026-03/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.

<Warning>
  **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.
</Warning>

Your response will look similar to the following:

```json theme={null}
{
  "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
    }
  ]
}
```

### Calculated properties

If your account has a *Professional* or *Enterprise* subscription, you can track how many [calculation properties](https://knowledge.hubspot.com/properties/create-calculation-properties) you've created. To track calculation property usage overall and per object, make a `GET` request to `crm/limits/2026-03/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 a `usage` value, which refers to the number of calculation properties you've created for the object.

Your response would look similar to the following:

```json theme={null}
{
  "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
    }
  ]
}
```

## Retrieve pipeline limits and usage

To view pipeline limits and usage per object, make a `GET` request to `crm/limits/2026-03/pipelines`.

Default objects with [pipelines](/api-reference/latest/crm/pipelines/guide) 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](#retrieve-custom-object-limits-and-usage).

Your response will look similar to the following:

```json theme={null}
{
  "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
      }
    ]
  }
}
```

## Retrieve custom object limits and usage

If your account has an *Enterprise* subscription, you can view limits and usage for the number of [custom objects](/api-reference/latest/crm/objects/schemas/guide#create-a-custom-object) in the account. If you want to view how many custom object <u>records</u> you can create, use the [record limits endpoint](#retrieve-record-limits-and-usage) instead.

To retrieve custom object limits and usage, make a `GET` request to `crm/limits/2026-03/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.

```json theme={null}
{
  "limit": 20,
  "usage": 4,
  "percentage": 20
}
```