Heap Analytics API
Provides a server-side REST API and JavaScript SDK for sending custom events, identifying users, and adding user properties to Heap's product analytics platform, which auto-captures all front-end interactions by default.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
The use of a public app_id (non-secret) for event ingestion is a notable security tradeoff — event spam or data poisoning is theoretically possible. Heap mitigates this with event validation rules. No scope granularity on ingestion.
⚡ Reliability
Best When
You want to enrich Heap's auto-captured front-end behavior data with server-side events and user properties to build complete product analytics without fully manual event instrumentation.
Avoid When
You need to programmatically query or export Heap analytics results — Heap's API is ingestion-only, so any downstream data access requires the Heap Connect warehouse integration.
Use Cases
- • Send server-side conversion events (subscription_upgraded, payment_processed) to Heap to enrich the auto-captured front-end session data with backend outcomes
- • Identify users server-side by associating anonymous session IDs with authenticated user identities after login to enable full-funnel analysis
- • Add user properties (plan_type, company_size, cohort_date) from a backend datastore to Heap to enable behavioral segmentation in reports
- • Track feature flag exposures from a server-side experimentation system as custom events to measure experiment impact in Heap
- • Backfill historical user properties or events during a data migration by posting to the server-side API in bulk
Not For
- • Exporting raw event data for warehouse ingestion (Heap has a separate Connect product for warehouse sync, not covered by the server API)
- • Querying or retrieving analytics results programmatically — Heap has no public query API; data is accessed via the UI or Connect
- • Real-time streaming analytics or event-driven alerting pipelines
Interface
Authentication
App ID (not a secret) is used in the JavaScript SDK. Server-side API uses the app_id in the request body — no secret key is required for event ingestion, which trades convenience for some security tradeoffs.
Pricing
Free tier is suitable for early-stage products. Server-side API access is included on all plans.
Agent Metadata
Known Gotchas
- ⚠ The app_id used for server-side event ingestion is the same public ID embedded in the browser JavaScript — it is not a secret, but this means anyone can POST events to your Heap app if they know the ID
- ⚠ Server-side API returns HTTP 200 even for malformed payloads; agents cannot use status codes to confirm successful event recording
- ⚠ User identity stitching requires that the anonymous identity (captured client-side) and the server-side user ID are linked via an addUserProperties or identify call before the session ends
- ⚠ Most server-side API endpoints do not support pagination as they are write-only ingestion endpoints — querying data requires the Heap Connect warehouse integration
- ⚠ Property names sent via the server API must match the format expected by Heap's schema; special characters or inconsistent casing create separate property definitions in reports
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for Heap Analytics API.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.