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

Authentication

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

• 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.

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.

---

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.