# Hotjar setup for PopMCP You paste two values into PopMCP: the client ID and client secret of a Hotjar API key, which an organization admin makes under Settings, then API. You can also add your site ID and organization ID, because Hotjar's API cannot look them up. A key belongs to one organization and stops working after one year. - Auth: API credentials - Setup time: 2 min - API base URL: https://api.hotjar.io/v1 - Credentials screen: https://insights.hotjar.com/settings/api - Provider docs: https://help.hotjar.com/hc/en-us/articles/36819965653009-How-to-Set-Up-the-Hotjar-API ## Approval required before this works Hotjar limits its API to Scale plans: Ask Scale gets survey responses and user lookup, Observe Scale gets user lookup and deletion only. - Typical wait: Immediate once your account is on a Scale plan, though Hotjar sells Scale through a sales call. - Cost: Scale plan pricing comes from Hotjar's sales team. Hotjar does not publish one API price. - Blocked until approved: Without a Scale plan every endpoint is out of reach. On Observe Scale without Ask Scale, the survey tools are refused and user lookup still works. - Works meanwhile: Hotjar's own survey export in its app needs no API. Nothing in PopMCP works until the key does. ## Before you begin - A Hotjar Scale plan: Ask Scale for surveys and user lookup, or Observe Scale for user lookup only - An Admin role in the Hotjar organization, because only admins can make API keys - Nothing to apply for: the key works as soon as it is made ## Get your credentials ### 1. Open the API page Sign in to Hotjar as an organization admin. Open Settings, then click API. The API page lists any keys made before. Screen: https://insights.hotjar.com/settings/api ### 2. Generate a key Select the Organization for the key and enter a Credential name such as `PopMCP`. Under Scope, select everything offered so surveys and user lookup both work, or only what you want your AI to reach. Click Generate credentials. Screen: https://insights.hotjar.com/settings/api ### 3. Copy the client ID and client secret Copy the client ID and the client secret of the new key. Keep them somewhere safe until you have pasted them into PopMCP. Hotjar keys stop working one year after they are made and cannot be extended. Screen: https://insights.hotjar.com/settings/api ### 4. Find your site ID Open Sites & Organizations. Each site shows its site ID, a number, and the organization ID is next to the organization. Note the site ID for surveys. You need the organization ID only for looking up or deleting a visitor's data. Hotjar's API cannot list these, so this is the one place to read them. Screen: https://insights.hotjar.com/site/list ### 5. Connect in PopMCP Paste the Client ID and Client secret into PopMCP's Hotjar form, add the Site ID if you have it, and click Connect. Add several site IDs with commas. Your AI then works with those sites only. Leave it empty and your AI will ask you for a site ID when it needs one. The Organization ID is under More options. Screen: https://help.hotjar.com/hc/en-us/articles/36819965653009-How-to-Set-Up-the-Hotjar-API ## Fields PopMCP asks for - Client ID (clientId) [required]: In Hotjar open Settings, then API, choose the organization, name the key, select the scope and click Generate credentials. Only organization admins can do this. - Client secret (clientSecret) [required]: From the same key. Stored encrypted and used only on our servers. - Site ID (siteIds): Optional, and it saves your AI asking. It is the number shown for each site at https://insights.hotjar.com/site/list. Separate several with commas. Your AI will then work with these sites only. - Organization ID (organizationId): Only for looking up or deleting a visitor's data. It is the number next to the organization at https://insights.hotjar.com/site/list. Your AI can also ask you for it. ## Verify PopMCP shows the Hotjar connector as Connected, named after your site. It gets a token from Hotjar and reads one survey from each site you gave. If this key cannot read surveys on a site, a note says so and the connection stays, because user lookup may still work. ## Troubleshooting ### Hotjar did not accept this client ID and secret Cause: A value was copied with something extra or cut short, the key was deleted, it is more than a year old, or the account is not on a Scale plan. Fix: Copy both values again from Settings, then API, or make a new key and connect again. ### This key could not read surveys on a site Cause: The plan is Observe Scale, the key's scope leaves out survey responses, or the site belongs to another organization. Fix: Check the plan and the site's organization, then make a new key that includes survey responses. User lookup can still work on Observe Scale. ### Hotjar cannot find a site Cause: The site ID is mistyped. The organization ID is a different number and will not work here. Fix: Copy the site's number from the Sites & Organizations page, or leave the field empty. ### The connection worked and now every tool is refused Cause: Hotjar keys expire one year after they are made and cannot be extended. Fix: Make a new key under Settings, then API, and connect Hotjar again. ### My AI says it cannot see recordings or heatmaps Cause: Hotjar's API has no endpoint for them, on any plan. Fix: Open them in Hotjar. A survey response can carry a link to its recording. ### A survey id is not found Cause: The number in a Hotjar page address is not the id the API uses. API ids look like survey_f5937a53-674a-43d1-b4b7-ada420568ebf. Fix: Ask your AI to find the survey by name. It will look up the right id. --- Source: https://www.docs.popmcp.com/docs/integrations/hotjar/