> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Hotjar

The Hotjar connector lets your AI agent act in each user's Hotjar account. Each user signs in to Hotjar once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 5 tools.

**Authentication:** Hotjar API Key (OAuth 2.0 Client Credentials)
**Categories:** Analytics
**Tools:** 5: 3 read, 1 write, 1 destructive
**Users sign in with:** Service account
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=HOTJAR)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Hotjar connection

   In **AgentKit > Connections**, create a Hotjar connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'hotjar_survey_get',
  toolInput: {
    site_id: '<site_id>',
    survey_id: '<survey_id>',
  },
  connector: 'hotjar',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="hotjar_survey_get",
    tool_input={
        "site_id": "<site_id>",
        "survey_id": "<survey_id>",
    },
    connection_name="hotjar",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `hotjar_survey_get`

Get Survey · Read-only

Get one Hotjar survey by ID, always with its questions.
Returns the survey's id, name, type, enabled flag, timestamps, sentiment analysis flag and questions (id, type, text, required flag, choices and labels).
Use this when you have a survey ID. Use hotjar_surveys_list to find one and hotjar_survey_responses_list for its answers.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `site_id` (`string`, required): The Hotjar site ID. Find it in Hotjar under Sites & Organizations, next to the site. Example: 1234567.
- `survey_id` (`string`, required): The survey ID, as returned in the id field by hotjar_surveys_list. Example: survey_f5937a53-674a-43d1-b4b7-ada420568ebf.

Example input: `{"site_id":"<site_id>","survey_id":"<survey_id>"}`

### `hotjar_survey_responses_list`

List Survey Responses · Read-only

List the responses to a Hotjar survey, newest first, one page at a time. Hotjar does not support filtering responses.
Returns each response's id, answers (question_id, answer, comment, tags and sentiment), completion flag, created_time, country, device, browser, OS, origin URL, recording URL, Hotjar user ID and user attributes, plus next_cursor.
Use this to read survey answers. Match question_id to the questions from hotjar_survey_get.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `site_id` (`string`, required): The Hotjar site ID. Find it in Hotjar under Sites & Organizations, next to the site. Example: 1234567.
- `survey_id` (`string`, required): The survey ID, as returned in the id field by hotjar_surveys_list. Example: survey_f5937a53-674a-43d1-b4b7-ada420568ebf.
- `cursor` (`string`, optional): Cursor for the next page: pass the next_cursor value from the previous hotjar_survey_responses_list response. Leave empty for the first page.
- `limit` (`integer`, optional): Number of responses to return per page, up to 100. Leave empty for Hotjar's default page size.

Example input: `{"site_id":"<site_id>","survey_id":"<survey_id>"}`

### `hotjar_surveys_list`

List Surveys · Read-only

List the surveys on a Hotjar site, one page at a time.
Returns each survey's id, name, type (link, full_screen or popover), enabled flag, timestamps and responses URL, plus questions when with_questions is true, and next_cursor.
Use this to find a survey ID. Use hotjar_survey_get for one survey's questions and hotjar_survey_responses_list for its answers.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `site_id` (`string`, required): The Hotjar site ID. Find it in Hotjar under Sites & Organizations, next to the site. Example: 1234567.
- `cursor` (`string`, optional): Cursor for the next page: pass the next_cursor value from the previous hotjar_surveys_list response. Leave empty for the first page.
- `limit` (`integer`, optional): Number of surveys to return per page, up to 100. Leave empty for Hotjar's default page size.
- `with_questions` (`boolean`, optional): Set to true to include each survey's questions in the response. Defaults to false.

Example input: `{"site_id":"<site_id>"}`

### `hotjar_user_lookup_request`

Request User Data Lookup · Write

Start a data subject lookup for one person across a Hotjar organization, without deleting anything.
Returns 202 Accepted with no body; Hotjar emails a link to the data report to the data subject's email and to the organization's default User Lookup recipient.
Use this for a data access request. Use hotjar_user_data_delete to erase the person's data instead.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `organization_id` (`string`, required): The Hotjar organization ID. Find it in Hotjar under Sites & Organizations, next to the organization. Example: 987654.
- `data_subject_email` (`string`, optional): Email address of the person whose data to look up. Send this, data_subject_site_id_to_user_id_map, or both. Example: jane@example.com.
- `data_subject_site_id_to_user_id_map` (`object`, optional): Map of Hotjar site ID to the user ID your site sent through the Hotjar Identify (User Attributes) API, for each site where the person may appear. Send this, data_subject_email, or both. Example: {"1234567": "user_42"}.

Example input: `{"organization_id":"<organization_id>"}`

### `hotjar_user_data_delete`

Delete User Data · Destructive

Find and permanently delete all Hotjar data for one person across an organization. This cannot be undone and sends no email or report.
Returns 202 Accepted with no body.
Use this for a data erasure request. Use hotjar_user_lookup_request to get a report without deleting.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `organization_id` (`string`, required): The Hotjar organization ID. Find it in Hotjar under Sites & Organizations, next to the organization. Example: 987654.
- `data_subject_email` (`string`, optional): Email address of the person whose data to look up. Send this, data_subject_site_id_to_user_id_map, or both. Example: jane@example.com.
- `data_subject_site_id_to_user_id_map` (`object`, optional): Map of Hotjar site ID to the user ID your site sent through the Hotjar Identify (User Attributes) API, for each site where the person may appear. Send this, data_subject_email, or both. Example: {"1234567": "user_42"}.

Example input: `{"organization_id":"<organization_id>"}`

## Related

Other Analytics connectors ([all 177](/agentkit/connectors/?category=analytics)):

- [Google Sheets](/agentkit/connectors/googlesheets/): Scalekit connector, OAuth, 48 tools
- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [AWS Redshift](/agentkit/connectors/redshift/): Scalekit connector, Trusted identity provider, 10 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
