> **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 Heap

The Heap connector lets your AI agent act in each user's Heap account. Each user connects their own Heap API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 7 tools.

**Authentication:** API Key
**Categories:** Analytics
**Tools:** 7: 0 read, 7 write, 0 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=HEAP)

## 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 Heap connection

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

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'heap'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Heap:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'heap_account_properties_bulk_add',
     toolInput: { accounts: [] },
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "heap"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Heap:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={"accounts":[]},
       tool_name="heap_account_properties_bulk_add",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Heap credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## 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: 'heap_account_properties_add',
  toolInput: {
    account_id: '<account_id>',
    properties: {
      plan: 'Pro',
      seats: 12,
    },
  },
  connector: 'heap',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="heap_account_properties_add",
    tool_input={
        "account_id": "<account_id>",
        "properties": {
            "plan": "Pro",
            "seats": 12,
        },
    },
    connection_name="heap",
    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.

### `heap_account_properties_add`

Add Account Properties · Write

Set custom properties on one account in Heap, such as payment tier or account owner. The Account ID setting must be configured in Heap first.
Returns an empty JSON object on success.
Use this for one account. Use heap_account_properties_bulk_add for up to 1,000 accounts. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `account_id` (`string`, required): The account ID, matching the value Heap uses as the account ID property. Example: acme-corp.
- `properties` (`object`, required): Key-value properties to attach to the account. Each key and value must be a number or a string under 1024 characters. Example: {"plan": "Pro", "seats": 12}.

Example input: `{"account_id":"<account_id>","properties":{"plan":"Pro","seats":12}}`

### `heap_account_properties_bulk_add`

Bulk Add Account Properties · Write

Set custom properties on up to 1,000 accounts in Heap in one request. The Account ID setting must be configured in Heap first.
Returns an empty JSON object on success.
Use this for many accounts. Use heap_account_properties_add for one. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `accounts` (`array`, required): Accounts to update, at most 1,000. Each item has an account_id and a properties object. Example: [{"account_id": "acme-corp", "properties": {"subscription": "Yearly"}}].

Example input: `{"accounts":[{"account_id":"acme-corp","properties":{"subscription":"Yearly"}}]}`

### `heap_event_track`

Track Event · Write

Send one custom event for a user to Heap from the server, such as a completed order or a sent email.
Returns an empty JSON object on success.
Use this for a single event. Use heap_events_bulk_track for up to 1,000 events at once. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `event` (`string`, required): Name of the custom event, up to 1024 characters. Name events broadly and use properties for details. Example: Send Transactional Email.
- `idempotency_key` (`string`, optional): A unique ID for this event. Heap ignores later calls with the same key, so retries do not create duplicates. Example: order-10045-completed.
- `identity` (`string`, optional): The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Provide identity or user_id, not both. Example: alice@example.com.
- `properties` (`object`, optional): Key-value properties to attach to the event. Each key and value must be a number or a string under 1024 characters. Array values are stored as one string joined with ||. Example: {"plan": "Pro", "seats": 12}.
- `session_id` (`string`, optional): Identifier of the user's session to attach the event to. Example: 7372837920834.
- `timestamp` (`string`, optional): When it happened, in ISO 8601. Defaults to the current time. Example: 2026-03-10T22:21:56+00:00.
- `user_id` (`string`, optional): The anonymous user_id from the Heap SDK: a whole number between 0 and 2^53 - 1, sent as a string. Provide identity or user_id, not both. Example: 3482937204597382.

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

### `heap_events_bulk_track`

Bulk Track Events · Write

Send up to 1,000 custom events to Heap in one request.
Returns an empty JSON object on success.
Use this to backfill or batch events. Use heap_event_track for one event. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `events` (`array`, required): Events to send, at most 1,000. Each event needs an event name and either identity or user_id, and can have timestamp (ISO 8601), properties, session_id and idempotency_key. Example: [{"identity": "alice@example.com", "event": "Phone Call", "timestamp": "2026-05-10T22:21:56+00:00", "properties": {"Duration": "15 minutes"}}].

Example input: `{"events":[{"identity":"alice@example.com","event":"Phone Call","timestamp":"2026-05-10T22:21:56+00:00","properties":{"Duration":"15 minutes"}}]}`

### `heap_user_identify`

Identify User · Write

Attach a known identity, such as an email, to an anonymous Heap user so that all of that user's events move to the identified user.
Returns an empty JSON object on success. Heap maps at most one identity to a user_id and at most 10 user_ids to an identity per month, and drops calls past those limits.
Use this to merge an anonymous visitor into a known user. Use heap_user_properties_add to set properties on a user. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `identity` (`string`, required): The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Example: alice@example.com.
- `user_id` (`string`, required): The anonymous user_id from the Heap SDK: a whole number between 0 and 2^53 - 1, sent as a string. Example: 3482937204597382.
- `timestamp` (`string`, optional): When it happened, in ISO 8601. Defaults to the current time. Example: 2026-03-10T22:21:56+00:00.

Example input: `{"identity":"<identity>","user_id":"<user_id>"}`

### `heap_user_properties_add`

Add User Properties · Write

Set custom properties on one identified Heap user, such as sign-up date or plan. Existing properties with the same name are overwritten, and a user is created if the identity is new.
Returns an empty JSON object on success.
Use this for one user. Use heap_user_properties_bulk_add for up to 1,000 users. To fill Heap's built-in Email property, use the lowercase key email. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `identity` (`string`, required): The user's identity in Heap, usually an email address or your own user ID. Case-sensitive, up to 255 characters. If no user has this identity, Heap creates one. Example: alice@example.com.
- `properties` (`object`, required): Key-value properties to attach to the user. Each key and value must be a number or a string under 1024 characters. Example: {"plan": "Pro", "seats": 12}.

Example input: `{"identity":"<identity>","properties":{"plan":"Pro","seats":12}}`

### `heap_user_properties_bulk_add`

Bulk Add User Properties · Write

Set custom properties on up to 1,000 identified Heap users in one request.
Returns an empty JSON object on success.
Use this for many users. Use heap_user_properties_add for one. The connection adds your environment ID (app_id) to the request body.

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

Inputs:

- `users` (`array`, required): Users to update, at most 1,000. Each item has an identity and a properties object. Use the lowercase key email to fill Heap's built-in Email property. Example: [{"identity": "alice@example.com", "properties": {"Role": "Admin"}}].

Example input: `{"users":[{"identity":"alice@example.com","properties":{"Role":"Admin"}}]}`

## 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 |
