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

# HubSpot

> Query HubSpot deals, contacts and companies live from Explore and AI agents

The HubSpot [live data source](https://docs.lightdash.com/integrations/live-data-sources) reads your HubSpot CRM deals, contacts and companies, each as its own table. Lightdash turns each query into a HubSpot CRM search and shows the records HubSpot returns. CRM data stays in HubSpot. It's a [level 2](https://docs.lightdash.com/integrations/live-data-sources#integration-levels) integration: its API filters records and reports a total, but doesn't group.

## Before you start

* **Live data sources enabled** for your organization. See [Live data sources](https://docs.lightdash.com/integrations/live-data-sources).
* **Admin role** in the Lightdash project.
* **A private app access token.** In HubSpot, go to **Settings** → **Integrations** → **Private Apps**, create an app, and give it read scopes for all three objects: `crm.objects.deals.read`, `crm.schemas.deals.read`, `crm.objects.contacts.read`, `crm.schemas.contacts.read`, `crm.objects.companies.read` and `crm.schemas.companies.read`. Copy the app's access token.

## Connect HubSpot

1. On the nav bar, click **Browse** → **Semantic Layer**.
2. In the sidebar, select **Live data sources**, then click **Add**.
3. Select **HubSpot**.
4. Enter a **Name**, such as `HubSpot`. People see this name in Explore and agents use it to refer to the source.
5. Enter the **Access token**, then click **Test access**.
6. Click **Add source**.

Lightdash adds **Deals**, **Contacts** and **Companies** tables to Explore, grouped under the source's name.

## Dimensions and metrics

Each table has these fields:

| Field | Notes |
| - | - |
| Record ID | The record's ID in HubSpot |
| Created, Last modified | When the record was created and last changed, in UTC |
| One for each property of the object | Read from HubSpot when you add the source, up to 400 per table. Hidden properties and property types Lightdash can't read are skipped. Properties start out of use: pick the ones people need on each table in the Semantic Layer |
| Count (metric) | How many records match the filters, from the total HubSpot reports. It can't be split by a dimension |

Select **Refresh fields** from the source's menu to read the properties again after you add one in HubSpot. A property's field is named after its internal name, so renaming its label in HubSpot doesn't change it.

Dropdown, radio and checkbox properties show HubSpot's internal option values, such as `closedwon`, not their labels. Filter with those values; each field's description lists them.

Text properties can be filtered with equals and contains, which matches whole words or part of one word. Number, date, checkbox and dropdown properties can be filtered too.

Date filters work on whole days in UTC and can look ahead, which suits fields like a deal's close date: **in the next 90 days** runs from today, and **in the current month** covers the whole month, including days still to come.

## Supported features

| Feature | Available |
| - | - |
| Filters on dimensions, with several values each | Yes |
| OR filters and nested filter groups | No |
| Sorting | One field at a time |
| Filters on metrics | No |
| Table calculations, custom metrics and custom dimensions | No |
| Period-over-period comparisons, pivots and date zoom | No |

## Limits

| Limit | Value |
| - | - |
| Most rows per query | 1,000 |
| Filter conditions per query | 6, with a date range counting as two |
| Timeout | 30 seconds per request |
| Queries at once | 2 per source |
| Calls per minute | 240 per source |
| Calls per hour | 10,000 per source |

When more records match than a query reads, Lightdash shows the first ones in the sort order you picked. Add a filter, or use **Count** to see how many match.

## Example questions

* *"How many deals in the closed won stage closed this quarter?"*
* *"Contacts created in the last 7 days, with their email and lifecycle stage."*
* *"The 50 largest open deals, by amount."*
* *"Open deals closing in the next 90 days, by close date."*

## Troubleshooting

**HubSpot rejected the access token.** Copy the private app's token again, or rotate it, and update the source.

**The private app is missing a scope.** Give it the read scopes for deals, contacts and companies listed in [Before you start](#before-you-start).

**HubSpot rate limit reached.** HubSpot allows a few searches a second per account. Wait a few seconds and run the query again.

**Count can't be split by a field.** Filter by the field instead, or list records without **Count**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.