Hotjar
Connect Hotjar to read and summarize your survey responses, track NPS, and look up or delete a visitor's data. MCP setup guide for Claude and ChatGPT.
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.
Paid plan required before this connector 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.
Where to apply: Book a call with Hotjar's sales team to move to Ask Scale or Observe Scale. Then an organization admin makes a key under Settings, then API.
- Only organization admins can make API keys.
- Keys expire one year after they are made and cannot be extended, so a working connection stops on that date until you make a new key and connect again.
- A key belongs to the one organization chosen when it was made, and its scope limits what it can do.
- The API does not cover recordings or heatmaps on any plan.
- Setup time
- 2 min
- Auth
- API credentials
- API base URL
- https://api.hotjar.io/v1
- Rate limits
- Hotjar allows 3000 requests per minute per source address and answers 429 when that is passed. PopMCP reuses each token for about an hour and reads pages of a survey one at a time.
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
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.
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.
API
Credentials for your organization.
This view is a simplified sketch: the labels on your page may differ slightly.
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.
API
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.
Sites & Organizations
- Organization
- Acme Inc (123456)
- Site
- shop.example.com (1234567)
This view is a simplified sketch: the labels on your page may differ slightly.
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.
Connect in PopMCP
Open your workspace, choose Hotjar in the marketplace, and fill in the connect dialog:
| Field | What to enter |
|---|---|
| Client IDtext | 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 secretsecret | From the same key. Stored encrypted and used only on our servers.Encrypted with AES-256-GCM on save and never shown again. |
| Site IDtext | 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 IDtext | 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. |
PopMCP verifies the credential against Hotjar immediately. On success the connection flips to Verified and its MCP tools are provisioned.
Verify it worked
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
Why: 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
Why: 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
Why: 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
Why: 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
Why: 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
Why: 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.