Build with the Humblytics API

Getting Started

The Humblytics API gives you programmatic access to all your analytics, heatmap, funnel, A/B test, and revenue attribution data. Use it to build custom dashboards, power LLM-driven agents, or integrate conversion data into your existing tools.

Property API access is available on every paid plan, including Plus. Agent API access for Claude and Codex starts on Business.

Quick Start

1. Sign up at app.humblytics.com and install the tracking script on your site
2. Go to Settings → API in your dashboard to generate an API key
3. Make your first request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.humblytics.com/v1/analytics/summary?site_id=YOUR_SITE_ID&period=7d

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings → API.

// Every request needs this header
Authorization: Bearer hm_live_abc123...

// Example with fetch
const response = await fetch('https://api.humblytics.com/v1/analytics/summary', {
  headers: {
    'Authorization': 'Bearer hm_live_abc123...',
    'Content-Type': 'application/json',
  },
});

API keys are scoped to a specific site. If you manage multiple sites, generate a key per site or use an organization-level key on Enterprise plans.

Core Endpoints

Base URL: https://api.humblytics.com/v1

Analytics Summary

GET /analytics/summary?site_id={id}&period={7d|30d|90d}

// Response
{
  "visitors": 12480,
  "page_views": 34210,
  "bounce_rate": 0.42,
  "avg_session_duration": 184,
  "top_pages": [
    { "path": "/pricing", "views": 4820, "unique": 3200 },
    { "path": "/", "views": 3910, "unique": 2800 }
  ],
  "sources": [
    { "source": "google", "visitors": 5200, "conversions": 312 },
    { "source": "direct", "visitors": 3100, "conversions": 186 }
  ]
}

Heatmap Data

GET /heatmaps?site_id={id}&page={url_path}&type={click|scroll|rage}

// Response
{
  "page": "/pricing",
  "type": "click",
  "total_clicks": 8420,
  "elements": [
    { "selector": "#cta-button", "clicks": 1240, "pct": 14.7 },
    { "selector": ".pricing-card-business", "clicks": 890, "pct": 10.6 }
  ],
  "scroll_depth": {
    "25": 0.92, "50": 0.74, "75": 0.51, "100": 0.28
  }
}

Funnel Analysis

GET /funnels/{funnel_id}?site_id={id}&period={30d}

// Response
{
  "funnel_id": "checkout-flow",
  "steps": [
    { "name": "Landing Page", "visitors": 10000, "drop_off": 0 },
    { "name": "Pricing", "visitors": 4200, "drop_off": 0.58 },
    { "name": "Checkout", "visitors": 1890, "drop_off": 0.55 },
    { "name": "Purchase", "visitors": 840, "drop_off": 0.56 }
  ],
  "overall_conversion": 0.084,
  "revenue": 42000
}

A/B Test Results

GET /experiments/{experiment_id}?site_id={id}

// Response
{
  "experiment_id": "pricing-cta-test",
  "status": "running",
  "variants": [
    {
      "name": "Control",
      "visitors": 4821,
      "conversions": 154,
      "conversion_rate": 0.032,
      "revenue": 12180
    },
    {
      "name": "Variant B",
      "visitors": 4790,
      "conversions": 244,
      "conversion_rate": 0.051,
      "revenue": 19320
    }
  ],
  "confidence": 0.95,
  "improvement": 0.594,
  "winner": "Variant B"
}

Revenue Attribution

GET /revenue?site_id={id}&period={30d}&group_by={source|page|experiment}

// Response
{
  "total_revenue": 84200,
  "by_source": [
    { "source": "google_ads", "revenue": 32100, "roas": 4.2 },
    { "source": "meta_ads", "revenue": 18400, "roas": 2.8 },
    { "source": "organic", "revenue": 22300 }
  ],
  "by_experiment": [
    { "experiment": "pricing-cta-test", "variant": "B", "revenue": 19320 }
  ]
}

Client-Side Event Tracking

The Humblytics script exposes a JavaScript API for tracking custom events directly from your site. Events flow into your analytics and can be used as funnel steps or conversion goals.

// Track a custom click event
window.Humblytics.trackClickEvent("signup-button-clicked", {
  domain: "yourmainsite.com"
});

// Track a form submission
window.Humblytics.trackFormSubmission("newsletter-signup", {
  domain: "yourmainsite.com"
});

// Track a custom conversion (e.g., from a SPA)
window.Humblytics.trackConversion("purchase-complete", {
  value: 79.00,
  currency: "USD"
});

Using the API with LLMs

The Humblytics API is designed to work as a tool for LLMs. Feed your analytics data into any model — Claude, GPT-4, Gemini — and get intelligent analysis, test hypotheses, and optimization recommendations.

Tool Definition for Claude

// Define Humblytics as a tool for Claude
const tools = [
  {
    name: "get_analytics_summary",
    description: "Get website analytics summary including visitors, page views, bounce rate, top pages, and traffic sources for a given period.",
    input_schema: {
      type: "object",
      properties: {
        period: {
          type: "string",
          enum: ["7d", "30d", "90d"],
          description: "Time period for the analytics data"
        }
      },
      required: ["period"]
    }
  },
  {
    name: "get_funnel_analysis",
    description: "Get conversion funnel data showing visitor drop-off at each step, with revenue attribution.",
    input_schema: {
      type: "object",
      properties: {
        funnel_id: { type: "string" },
        period: { type: "string", enum: ["7d", "30d", "90d"] }
      },
      required: ["funnel_id"]
    }
  },
  {
    name: "get_experiment_results",
    description: "Get A/B test results including conversion rates, revenue per variant, statistical confidence, and the winning variant.",
    input_schema: {
      type: "object",
      properties: {
        experiment_id: { type: "string" }
      },
      required: ["experiment_id"]
    }
  },
  {
    name: "get_heatmap_data",
    description: "Get click and scroll heatmap data for a specific page.",
    input_schema: {
      type: "object",
      properties: {
        page: { type: "string", description: "URL path like /pricing" },
        type: { type: "string", enum: ["click", "scroll"] }
      },
      required: ["page", "type"]
    }
  }
];

Example: AI Conversion Analyst

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const HUMBLYTICS_API_KEY = process.env.HUMBLYTICS_API_KEY;
const SITE_ID = process.env.HUMBLYTICS_SITE_ID;

// Handle tool calls by fetching from Humblytics API
async function handleToolCall(name: string, input: Record<string, string>) {
  const base = "https://api.humblytics.com/v1";
  const headers = {
    Authorization: `Bearer ${HUMBLYTICS_API_KEY}`,
    "Content-Type": "application/json",
  };

  switch (name) {
    case "get_analytics_summary":
      return fetch(`${base}/analytics/summary?site_id=${SITE_ID}&period=${input.period}`, { headers }).then(r => r.json());
    case "get_funnel_analysis":
      return fetch(`${base}/funnels/${input.funnel_id}?site_id=${SITE_ID}&period=${input.period || "30d"}`, { headers }).then(r => r.json());
    case "get_experiment_results":
      return fetch(`${base}/experiments/${input.experiment_id}?site_id=${SITE_ID}`, { headers }).then(r => r.json());
    case "get_heatmap_data":
      return fetch(`${base}/heatmaps?site_id=${SITE_ID}&page=${input.page}&type=${input.type}`, { headers }).then(r => r.json());
  }
}

// Ask Claude to analyze your conversion data
const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 4096,
  tools,
  messages: [
    {
      role: "user",
      content: "Analyze why our checkout conversion dropped this week. Check the funnel data and heatmaps for the pricing page."
    }
  ],
});

// Claude will call get_funnel_analysis and get_heatmap_data,
// then provide a plain-English analysis with recommendations.

Example: Generate Test Hypotheses

const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 4096,
  system: `You are a CRO analyst. When given analytics data from Humblytics,
    generate 5 prioritized A/B test hypotheses ranked by expected revenue impact.
    For each hypothesis, include:
    - What to test (specific element + change)
    - Why (data-backed rationale from the analytics)
    - Expected lift range
    - Estimated revenue impact per month`,
  tools,
  messages: [
    {
      role: "user",
      content: "What should we test next on our pricing page to increase conversions?"
    }
  ],
});

Building Custom Dashboards

Use the API to build real-time dashboards tailored to your team. Pull analytics, experiment results, and revenue data into any frontend framework.

React Dashboard Example

import useSWR from "swr";

const fetcher = (url: string) =>
  fetch(url, {
    headers: { Authorization: `Bearer ${process.env.NEXT_PUBLIC_HUMBLYTICS_KEY}` },
  }).then((r) => r.json());

function ConversionDashboard() {
  const { data: analytics } = useSWR(
    `https://api.humblytics.com/v1/analytics/summary?site_id=${SITE_ID}&period=7d`,
    fetcher,
    { refreshInterval: 30000 } // refresh every 30s
  );

  const { data: experiments } = useSWR(
    `https://api.humblytics.com/v1/experiments?site_id=${SITE_ID}&status=running`,
    fetcher
  );

  const { data: revenue } = useSWR(
    `https://api.humblytics.com/v1/revenue?site_id=${SITE_ID}&period=7d&group_by=source`,
    fetcher
  );

  return (
    <div className="grid grid-cols-3 gap-6">
      <MetricCard label="Visitors (7d)" value={analytics?.visitors} />
      <MetricCard label="Conversion Rate" value={analytics?.conversion_rate} />
      <MetricCard label="Revenue (7d)" value={revenue?.total_revenue} format="currency" />

      <ExperimentsList experiments={experiments?.active} />
      <RevenueBySource data={revenue?.by_source} />
      <TopPages pages={analytics?.top_pages} />
    </div>
  );
}

Building Slack Agents

Build custom Slack bots that answer conversion questions using your Humblytics data. Combine the Slack Bolt SDK with the Humblytics API and an LLM for intelligent responses.

Slack Bot with Claude + Humblytics

import { App } from "@slack/bolt";
import Anthropic from "@anthropic-ai/sdk";

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

const anthropic = new Anthropic();

// Listen for messages mentioning the bot
app.event("app_mention", async ({ event, say }) => {
  const question = event.text.replace(/<@[^>]+>/g, "").trim();

  // Fetch relevant data from Humblytics
  const [analytics, funnels, experiments] = await Promise.all([
    fetchHumblytics("/analytics/summary?period=7d"),
    fetchHumblytics("/funnels?period=7d"),
    fetchHumblytics("/experiments?status=running"),
  ]);

  // Ask Claude to analyze and respond
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    system: `You are a CRO analyst bot in Slack. Answer questions about website
      conversion data concisely. Use the provided analytics data. Format responses
      for Slack (use *bold*, bullet points, and emoji sparingly).`,
    messages: [
      {
        role: "user",
        content: `Question: ${question}

Analytics (7d): ${JSON.stringify(analytics)}
Active Funnels: ${JSON.stringify(funnels)}
Running Experiments: ${JSON.stringify(experiments)}`,
      },
    ],
  });

  await say(response.content[0].text);
});

// Scheduled daily summary
import cron from "node-cron";
cron.schedule("0 9 * * 1-5", async () => {
  const summary = await fetchHumblytics("/analytics/summary?period=1d");
  const experiments = await fetchHumblytics("/experiments?status=running");

  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 512,
    system: "Generate a brief daily CRO summary for Slack. Include key metrics, any anomalies, and experiment status updates.",
    messages: [{ role: "user", content: JSON.stringify({ summary, experiments }) }],
  });

  await app.client.chat.postMessage({
    channel: "#conversions",
    text: response.content[0].text,
  });
});

app.start(3000);

Webhooks & Revenue Tracking

Connect Stripe, Foxy, or any payment provider to attribute revenue to traffic sources, pages, and A/B test variants.

Stripe Integration

// 1. Connect Stripe in your Humblytics dashboard
// Settings → Revenue → Connect Stripe (one-click OAuth)

// 2. Revenue data flows automatically — no code needed.
// Humblytics matches Stripe payments to visitor sessions using
// first-party data (no cookies required).

// 3. Query revenue attribution via API
const revenue = await fetch(
  "https://api.humblytics.com/v1/revenue?site_id=YOUR_SITE&period=30d&group_by=experiment",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
).then(r => r.json());

// See which A/B test variants drive actual revenue
console.log(revenue.by_experiment);
// [{ experiment: "pricing-cta", variant: "B", revenue: 19320, roas: 4.2 }]

Custom Webhook

// Send purchase events from any payment provider
POST https://api.humblytics.com/v1/webhooks/purchase
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "site_id": "YOUR_SITE_ID",
  "visitor_id": "hm_vid_abc123",  // from Humblytics cookie-free session
  "amount": 79.00,
  "currency": "USD",
  "order_id": "order_12345",
  "source": "custom_checkout"
}

Rate Limits & Plans

Need higher limits? Contact us for Enterprise pricing with custom SLAs and dedicated support.