External Analytics API

Our External Analytics API lets you pull Humblytics traffic data programmatically using the same property-scoped API keys that power the in-app dashboards. This guide covers authentication, required parameters, endpoints, and typical responses.

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

In-App API Access Page

The Humblytics dashboard includes a dedicated API Access page (found under Utilities in the sidebar) that provides everything you need to get started with the API.

API Key Generation and Management

Use the Generate New Key button to create a new API key for your property. You can manage existing keys from this page, including revoking keys that are no longer needed. Each key is scoped to a single property.

Quick Start

The API Access page displays a Quick Start section with your property-specific details pre-filled:

• Property ID -- your unique property identifier

• Base URL -- https://app.humblytics.com/api/external/v1/

• Example curl request -- a ready-to-copy request you can run immediately to verify your setup

AI Agent Instructions

The API Access page also includes an AI Agent Instructions section with tabs for different AI coding tools:

• Claude Code -- copy-paste instructions for integrating the Humblytics API with Claude Code

• Cursor -- copy-paste instructions for integrating the Humblytics API with Cursor

• Generic -- general-purpose instructions that work with any AI coding assistant

These instructions provide your AI tool with the context it needs to query the Humblytics API on your behalf, including your property ID, API key, and available endpoints.

---

Authentication

• Generate an API key for your property in the Humblytics app (sidebar → Utilities → API).

• Include the key in every request using the Authorization header:

Authorization: Bearer <your_api_key>

• Keys are property-scoped. The propertyId in the request path must match the property linked to the API key, otherwise the API returns 403.

• Ensure the key has the metrics permission enabled.

API Access by Plan

API access is included on all plans. Generate API keys from the API Access page under Utilities in the sidebar.

• Plus, Business, Scale: API access included

• Enterprise: Full API access with custom endpoints and priority support

Versioning

All external endpoints live under /api/external/v1. Future versions will be published side-by-side (for example, /api/external/v2) so you can migrate when ready.

Common Parameters

Name	Type	Required	Notes
start	string	Yes	ISO-8601 timestamp or date (e.g. 2024-05-01 or 2024-05-01T00:00:00Z).
end	string	Yes	ISO-8601 timestamp or date that occurs after start.
timezone	string	No	IANA zone name (defaults to UTC). Determines bucket boundaries and how timestamps are formatted in responses.

Requests that cannot be parsed—invalid dates, unsupported timezones, end before start, ranges that are too large—return 400 with a descriptive error payload.

---

Traffic Trends

GET /properties/{propertyId}/traffic/trends

Returns time-series metrics for page views and unique visitors within a specified range.

Query Parameters

Name	Type	Required	Default	Notes
granularity	enum	No	day	Accepted values: hour, day, week, month.

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/traffic/trends?start=2024-05-01&end=2024-05-07&granularity=day&timezone=America/New_York"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T04:00:00.000Z",
    "end": "2024-05-07T03:59:59.000Z",
    "granularity": "day",
    "timezone": "America/New_York",
    "bucket_count": 7
  },
  "data": [
    {
      "bucket_start": "2024-05-01T00:00:00-04:00",
      "bucket_end": "2024-05-01T23:59:59-04:00",
      "page_views": 1523,
      "unique_visitors": 682
    }
  ],
  "summary": {
    "page_views": 9056,
    "unique_visitors": 3142
  }
}

Notes

• Buckets include zero-filled entries when no activity occurred so charting remains continuous.

• Maximum of 500 buckets per request. Very granular windows (for example, hourly over multiple months) return 400.

• The API excludes known bots automatically to align with the dashboard totals.

---

Traffic Breakdown

GET /properties/{propertyId}/traffic/breakdown

Returns the top traffic segments (UTM attributes, countries, devices, landing pages, and referrers) for a specified range.

Query Parameters

Name	Type	Required	Default	Notes
limit	number	No	10	Maximum entries per segment (maximum supported value: 50).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/traffic/breakdown?start=2024-05-01T00:00:00Z&end=2024-05-31T23:59:59Z&timezone=UTC&limit=20"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "timezone": "UTC",
    "limit": 20,
    "totals": {
      "sessions": 1982,
      "page_views": 5478
    }
  },
  "data": {
    "utm": [
      {
        "source": "google",
        "medium": "cpc",
        "campaign": "spring_launch",
        "sessions": 412,
        "page_views": 921,
        "share": 0.208
      }
    ],
    "countries": [
      {
        "country": "US",
        "sessions": 982,
        "page_views": 2015,
        "share": 0.495
      }
    ],
    "devices": [
      {
        "device": "desktop",
        "sessions": 1045,
        "page_views": 2684,
        "share": 0.527
      }
    ],
    "landing_pages": [
      {
        "path": "/pricing",
        "sessions": 213,
        "page_views": 425,
        "share": 0.107
      }
    ],
    "referrers": [
      {
        "referrer": "google",
        "sessions": 643,
        "page_views": 1580,
        "share": 0.324
      }
    ]
  }
}

Notes

• share represents the fraction of total sessions contributed by each row.

• Null or missing values are returned as "unknown" so you do not need to special-case missing fields.

• Device values are normalized (desktop, mobile, unknown) using Humblytics’ device classification.

---

Clicks Breakdown

GET /properties/{propertyId}/clicks/breakdown

Returns aggregated click event data grouped by page and click target, along with trend data over time.

Query Parameters

Name	Type	Required	Default	Notes
granularity	enum	No	day	Accepted values: hour, day, week, month.
limit	number	No	10	Maximum entries per segment (maximum supported value: 50).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/clicks/breakdown?start=2024-05-01&end=2024-05-07&granularity=day&timezone=UTC&limit=20"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-07T23:59:59.000Z",
    "timezone": "UTC",
    "granularity": "day",
    "limit": 20,
    "bucket_count": 7
  },
  "data": [
    {
      "page": "/pricing",
      "target": "Get Started Button",
      "clicks": 342,
      "unique_clicks": 289
    },
    {
      "page": "/home",
      "target": "Sign Up Link",
      "clicks": 128,
      "unique_clicks": 115
    }
  ],
  "trend": [
    {
      "bucket_start": "2024-05-01T00:00:00.000Z",
      "bucket_end": "2024-05-01T23:59:59.000Z",
      "clicks": 412,
      "unique_clicks": 352
    }
  ],
  "summary": {
    "total_clicks": 2849,
    "total_unique_clicks": 2341
  }
}

Notes

• Returns both page-level click aggregations and time-series trend data in a single response.

• Click targets are automatically extracted from tracked click events.

• unique_clicks counts distinct sessions that performed the click action.

---

Clicks Details

GET /properties/{propertyId}/clicks/details

Returns detailed click event breakdown for a specific page, showing which elements were clicked.

Query Parameters

Name	Type	Required	Default	Notes
page	string	Yes	N/A	The page path to get click details for (URL-encoded)
granularity	enum	No	day	Accepted values: hour, day, week, month.
limit	number	No	10	Maximum entries to return (maximum: 50).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/clicks/details?page=%2Fpricing&start=2024-05-01&end=2024-05-07&granularity=day&timezone=UTC&limit=20"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "page": "/pricing",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-07T23:59:59.000Z",
    "timezone": "UTC",
    "granularity": "day",
    "limit": 20,
    "bucket_count": 7
  },
  "data": {
    "clicks": [
      {
        "target": "Get Started Button",
        "clicks": 342,
        "unique_clicks": 289,
        "share": 0.473
      },
      {
        "target": "Learn More Link",
        "clicks": 128,
        "unique_clicks": 115,
        "share": 0.177
      }
    ]
  },
  "summary": {
    "total_clicks": 723,
    "total_unique_clicks": 615
  }
}

Notes

• Use URL encoding for the page parameter (e.g., /pricing page becomes %2Fpricing%20page).

• share represents the proportion of total clicks on that page attributed to each target.

• Returns only clicks that occurred on the specified page.

---

Forms Breakdown

GET /properties/{propertyId}/forms/breakdown

Returns aggregated form submission data grouped by page and form target, along with trend data over time.

Query Parameters

Name	Type	Required	Default	Notes
granularity	enum	No	day	Accepted values: hour, day, week, month.
limit	number	No	10	Maximum entries per segment (maximum supported value: 50).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/forms/breakdown?start=2024-05-01&end=2024-05-07&granularity=day&timezone=UTC&limit=20"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-07T23:59:59.000Z",
    "timezone": "UTC",
    "granularity": "day",
    "limit": 20,
    "bucket_count": 7
  },
  "data": [
    {
      "page": "/contact",
      "target": "Contact Form",
      "submissions": 89,
      "unique_submissions": 82
    },
    {
      "page": "/signup",
      "target": "Registration Form",
      "submissions": 156,
      "unique_submissions": 147
    }
  ],
  "trend": [
    {
      "bucket_start": "2024-05-01T00:00:00.000Z",
      "bucket_end": "2024-05-01T23:59:59.000Z",
      "submissions": 34,
      "unique_submissions": 31
    }
  ],
  "summary": {
    "total_submissions": 245,
    "total_unique_submissions": 229
  }
}

Notes

• Returns both page-level submission aggregations and time-series trend data in a single response.

• Form targets are automatically extracted from tracked form submission events.

• unique_submissions counts distinct sessions that submitted a form.

---

Forms Details

GET /properties/{propertyId}/forms/details

Returns detailed form submission breakdown for a specific page, showing which forms were submitted.

Query Parameters

Name	Type	Required	Default	Notes
page	string	Yes	N/A	The page path to get form details for (URL-encoded)
granularity	enum	No	day	Accepted values: hour, day, week, month.
limit	number	No	10	Maximum entries to return (maximum: 50).

Sample Request

curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/forms/details?page=%2Fcontact&start=2024-05-01&end=2024-05-07&granularity=day&timezone=UTC&limit=20"

Sample Response

{
  "meta": {
    "property_id": "PROPERTY_ID",
    "page": "/contact",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-07T23:59:59.000Z",
    "timezone": "UTC",
    "granularity": "day",
    "limit": 20,
    "bucket_count": 7
  },
  "data": {
    "forms": [
      {
        "target": "Contact Form",
        "submissions": 89,
        "unique_submissions": 82,
        "share": 0.687
      },
      {
        "target": "Newsletter Signup",
        "submissions": 41,
        "unique_submissions": 39,
        "share": 0.313
      }
    ]
  },
  "summary": {
    "total_submissions": 130,
    "total_unique_submissions": 121
  }
}

Notes

• Use URL encoding for the page parameter (e.g., /contact us becomes %2Fcontact%20us).

• share represents the proportion of total form submissions on that page attributed to each form.

• Returns only form submissions that occurred on the specified page.

---

Errors

Status	Code	When it happens
400	invalid_request	Bad dates, unsupported timezone or granularity, ranges that are too large.
401	unauthorized	Missing or invalid API key header.
403	forbidden	Property ID does not match the API key or the key does not have metrics permission.
429	rate_limited	Too many requests in a short window (limits will evolve with usage).
500	internal_error	Unexpected server error. Retry later or contact support.

Error payloads follow this structure:

{
  "error": {
    "code": "invalid_request",
    "message": "Unsupported granularity: minute",
    "details": {
      "field": "granularity"
    }
  }
}

---

Best Practices

• Store API keys securely (environment variables or a secret manager) and rotate them periodically.

• Use the timezone parameter to align data with the local reporting context you care about.

• Cache responses when possible—trend and breakdown data only changes when new traffic arrives.

• Start with coarser granularity (e.g. day) for large ranges, then request narrower windows for detailed analysis.

• Let us know if you need additional datasets; the roadmap for /api/external/v1 will continue to expand based on customer feedback.

• Looking for A/B testing endpoints? See the Split Testing API to get AI-powered test recommendations and create no-code experiments programmatically.