Heatmap GraphQL API Documentation

Welcome to the Heatmap consumer GraphQL API docs.

Use this documentation portal to discover endpoint behavior, authentication, query inputs, and practical examples for dashboard and reporting clients.

Start Here

• Authentication and Endpoint
• Schema and Inputs
• Metrics Glossary
• Query Recipes
• Errors and Troubleshooting
• Permissions and Access Scope
• Examples and Best Practices

Create an API Token

1. Go to portal.heatmap.com.
2. Click **Settings** (bottom left).
3. Select **Access Keys**.
4. Create an access key.
5. Copy the key immediately. It is shown only once, and we do not store the raw key.

Testing

1. Open https://insights-api.heatmapcore.com/graphql/v1 in your browser.
2. Add your token to the X-Access-Key request header.
3. Press Shift+Ctrl+R to refresh and load the schema.
4. Have fun testing.

API Contract Snapshot

• GraphQL endpoint: POST /graphql/v1
• Docs portal: GET /docs/v1
• Deprecated aliases: POST /graphql and GET /docs
• Auth transport: X-Access-Key header (preferred) or access_key query param
• Introspection and field availability are scoped by access rules in viewerAccess

Typical Flow

1. Run viewerAccess to understand your site and endpoint scope.
2. Load sites to get valid siteId values.
3. Build analytics queries with DateRangeInput and optional filters.
4. Add breakdown, sort, and limit only where needed for UI performance.

Core Query Groups

• Access and metadata: viewerAccess, sites
• Aggregated analytics: analytics, sessionAnalytics, pageviewAnalytics
• Journey and events: journeyContinuationAnalytics, rawPageviewAnalytics, rawEventAnalytics
• Product analytics: funnels, heatmap, conversions, customEvents