The connector only reads data. It never creates, changes or deletes anything in Hotjar. The Hotjar API does not export heatmaps or session recordings, so they are not available.
Configuring Hotjar as a Source
In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Hotjar option from the list of connectors. Click Next and you’ll be prompted to add your access.1. Add account access
The connector signs in with Hotjar API credentials (a Client ID and a Client Secret). Only a user with Admin permission in the Hotjar organization can create them:- In Hotjar, open Settings and click API.
- Select the organization that owns the sites you want to sync.
- Enter a name for the credentials (for example “Nekt”).
- Select the scope that gives access to survey responses.
- Click Generate credentials and copy the Client ID and the Client Secret.
- Client ID: The Client ID of the Hotjar API credentials.
- Client Secret: The Client Secret of the same credentials.
- Site IDs: The IDs of the Hotjar sites whose surveys you want to sync. Each Site ID is the number shown next to the site on the Sites & Organizations page in Hotjar. Every site must belong to the organization the credentials were generated for.
2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.Tip: The stream can be found more easily by typing its name.Select the streams and click Next.
3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.- Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
- Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
- Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
- Sync Type: every Hotjar table is synced as Full table: on every sync we read the current state of your surveys and responses. The Hotjar API cannot filter responses by date, and a response keeps changing after it is submitted (a partial response is completed, tags and sentiment are edited), so each sync reads everything again.
4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters. To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here. Once you are ready, click Next to finalize the setup.5. Check your new source
You can view your new source on the Sources page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.What happens when access is missing
- If the credentials are wrong, deleted or expired, the sync fails and no table is changed.
- If one of the Site IDs cannot be read with the credentials (a site of another organization, or a wrong number), the sync fails and no table is changed, because every table holds the data of all the sites.
- If the credentials can read the surveys but not the survey responses (the plan is not Ask Scale, or the credentials lack the survey responses scope), the Survey Responses and Survey Response Answers tables are skipped and not updated, the other tables keep syncing, and the sync log says what to fix.
- If a table that had rows comes back completely empty, that table’s sync fails instead of emptying it, and the log says so. If you really removed all that data in Hotjar, run a Full sync of the source to accept the empty table.
Streams and Fields
Available streams
The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description.Nested information (the options of a question, the user attributes and the answers of a response) comes as JSON text. To analyze answers, use Survey Response Answers, which already has one row per answer joined with its question.
Fields by stream
Surveys
Surveys
Every survey of the configured sites. Read in full on every sync.Table:
surveys · Primary key: id · Sync: Full tableSurvey Questions
Survey Questions
Every question of every survey, in the survey’s order. Read in full on every sync.Table:
survey_questions · Primary key: survey_id, id · Sync: Full tableSurvey Responses
Survey Responses
Every response to every survey. Read in full on every sync.Table:
survey_responses · Primary key: id · Sync: Full tableSurvey Response Answers
Survey Response Answers
One row per answer of every response, with the question’s text and type. Read in full on every sync.Table:
survey_response_answers · Primary key: response_id, answer_index · Sync: Full tableImplementation Notes
- Survey responses need an Ask Scale plan. On other plans Hotjar refuses survey responses through its API. Hotjar does not document whether the list of surveys (the Surveys and Survey Questions tables) is available on other plans; this will be confirmed on the first syncs. If Hotjar refuses only the responses, the two response tables are skipped and the survey tables keep syncing.
- Credentials expire after one year. Generate new ones in Hotjar (Settings > API) before they expire and update this source.
- Everything is read again on every sync. The Hotjar API returns responses newest first and cannot filter them by date, so each sync reads every response of every survey. Large accounts take longer to sync.
- Scores come as text. The
answerfield keeps the value as Hotjar sends it; cast it to a number in your queries for nps and rating questions (for exampleCAST(answer AS INT)). - Not available through the Hotjar API: heatmaps, session recordings, feedback widgets, funnels and events. The Hotjar User Lookup feature (privacy requests) is not used by this connector.