> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/external-analytics-api.md).

# External Analytics API

Our External Analytics API lets you pull Humblytics data programmatically — traffic, pages, clicks, forms, funnels, heatmaps and attribution — plus manage sites and billing from an agent, using the same API keys that power the Humblytics MCP server. This guide covers authentication, required parameters, endpoints, and typical responses.

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

## The Agents page

API keys live on the **Agents** page of the Humblytics dashboard (sidebar → **Agents**, or `/agent`). It is the activation console for the API and AI agents:

* **Connect an assistant** — sign your agent in over MCP with no key to paste (recommended)
* **API keys** tab — create, copy and revoke account and property keys (shown once at creation)
* **Skills** tab — copy a setup prompt to install the 12 [humblytics-marketing-skills](https://github.com/Humblytics/humblytics-marketing-skills)
* **REST reference** tab — a reference curl example you can run live against your site

See [MCP & API Access](https://docs.humblytics.com/api-access-and-agents.md) for the full walkthrough, the MCP tool catalog, security practices, and workflow examples.

***

## Authentication

* Create an API key on the **Agents** page (`/agent`, **API keys** tab).
* Include the key in every request using the `Authorization` header:

```http
Authorization: Bearer <your_api_key>
```

* **Account keys** (recommended) work for every site you own: any `propertyId` you own is accepted, and they are the only keys that can call the account, site-setup and billing endpoints.
* **Property keys** are scoped to one site. The `propertyId` in the request path must match the property linked to the key, otherwise the API returns `403`.
* Ensure the key has the `metrics` permission enabled (keys created on the Agents page have it).

## API Access by Plan

API and MCP access are included on every current plan: **Free start** (the first 5,000 data points, 1 site, no card), **Agents** ($39 one time for 100,000 data points over 12 months), **Business**, **Scale** and **Enterprise**. Only the legacy Free plan does not include API access. Reads and tool calls are never counted as data points; a data point is one tracked event.

## 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.                                                                                                              |
| `limit`        | number  | No                    | Maximum results to return. Defaults and caps differ by endpoint: traffic breakdown and entry/exit pages default 10 (max 50); clicks, pages and forms breakdowns default 50 (max 100); details endpoints default 20 (max 50). |
| `offset`       | number  | No                    | Rows to skip, for server-side pagination (breakdown and details endpoints). Default `0`.                                                                                                                                     |
| `search`       | string  | No                    | Filters breakdown rows by target name (clicks, pages and forms breakdowns).                                                                                                                                                  |
| `page`         | string  | For details endpoints | URL path to filter (e.g. `/pricing`). Required for detail endpoints.                                                                                                                                                         |
| `include_bots` | boolean | No                    | `true` includes classified bot traffic in traffic endpoints. Bots are excluded by default.                                                                                                                                   |

**Dimension filters.** Traffic, pages, clicks and forms endpoints accept `page`, `country`, `region`, `browser`, `os`, `device`, `utm_medium`, `utm_source` and `referrer` as query parameters to include only matching sessions, and `exclude_<field>` (for example `exclude_country=US`) to leave them out. Use `GET /properties/{propertyId}/filters` to list the values available for a date range.

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

```bash
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

```json
{
  "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.
* Range caps per granularity: `hour` up to 14 days, `day` and `week` up to 400 days, `month` up to 800 days, and never more than 500 buckets per request. Larger windows return `400`.
* The API excludes known bots automatically to align with the dashboard totals. Pass `include_bots=true` to include them.

***

## Traffic Summary

```
GET /properties/{propertyId}/traffic/summary
```

Returns aggregate traffic metrics for a specified range, including total page views, sessions, bounce rate, and average session duration.

### Sample Request

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

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T04:00:00.000Z",
    "end": "2024-05-07T03:59:59.000Z",
    "timezone": "America/New_York"
  },
  "data": {
    "page_views": 9056,
    "unique_visitors": 2418,
    "total_sessions": 3142,
    "bounce_count": 1329,
    "single_page_sessions": 1402,
    "total_session_time_ms": 579699000,
    "form_submissions": 86,
    "clicks": 1204,
    "avg_session_duration": 184.5,
    "bounce_rate": 0.423,
    "single_page_bounce_rate": 0.446
  }
}
```

### Notes

* `bounce_rate` and `single_page_bounce_rate` are decimals (e.g. `0.423` = 42.3%).
* `avg_session_duration` is in seconds; `total_session_time_ms` is in milliseconds.
* Bot traffic is excluded automatically unless `include_bots=true`.

***

## Bot Traffic

```
GET /properties/{propertyId}/traffic/bots
GET /properties/{propertyId}/traffic/bots-comparison
```

`/traffic/bots` returns the bot traffic Humblytics filtered out of the human totals for the range (`page_views`, `unique_visitors`, `actions`). `/traffic/bots-comparison` puts bots and humans side by side. Both accept `start`, `end`, `timezone` and the dimension filters.

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/traffic/bots-comparison?start=2024-05-01&end=2024-05-31"
```

### Sample Response

```json
{
  "meta": { "property_id": "PROPERTY_ID", "start": "2024-05-01T00:00:00.000Z", "end": "2024-05-31T23:59:59.000Z", "timezone": "UTC" },
  "data": {
    "bot": {
      "page_views": 812,
      "unique_visitors": 390,
      "pct": 13,
      "sessions": 390,
      "sessions_pct": 11,
      "reasons": { "user_agent": 260, "datacenter_asn": 130 },
      "top_sources": [{ "label": "Googlebot", "kind": "user_agent", "sessions": 120 }]
    },
    "human": {
      "page_views": 5478,
      "unique_visitors": 3142,
      "pct": 87,
      "sessions": 3142,
      "sessions_pct": 89,
      "cloud_browser": { "sessions": 24, "page_views": 40, "sessions_pct": 1, "providers": [], "top_pages": [] }
    },
    "total": { "page_views": 6290, "unique_visitors": 3532, "sessions": 3532 }
  }
}
```

### Notes

* `pct` is a share of page views; `sessions_pct` is a share of sessions. `reasons` always lists every classification reason, zero-filled.
* `human.cloud_browser` is the subset of human sessions that came from a hosting network (AWS, Azure, Google Cloud and similar). It is informational — those sessions stay in the human totals.

***

## Traffic Realtime

```
GET /properties/{propertyId}/traffic/realtime
```

Returns the current live visitor count and a feed of recent visitor activity. This endpoint does **not** require `start`, `end`, or `timezone` parameters.

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/traffic/realtime"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID"
  },
  "data": {
    "active_visitors": 23,
    "live_feed": [
      {
        "page": "/pricing",
        "referrer": "google",
        "device": "desktop",
        "country": "US",
        "timestamp": "2024-05-07T14:32:18.000Z"
      }
    ]
  }
}
```

### Notes

* This endpoint returns a snapshot of current activity — no date range parameters are needed.
* The `live_feed` array shows the most recent visitor events in reverse chronological order.
* `active_visitors` reflects sessions active within the last few minutes.

***

## 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). |

Dimension filters and `include_bots` are also accepted.

### Sample Request

```bash
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

```json
{
  "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.

***

## Traffic Entry & Exit Pages

```
GET /properties/{propertyId}/traffic/entry-exit-pages
```

Returns the top entry pages (where sessions begin) and exit pages (where sessions end) for a specified range.

### Query Parameters

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

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/traffic/entry-exit-pages?start=2024-05-01&end=2024-05-31&timezone=UTC&limit=10"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "limit": 10
  },
  "data": {
    "entry_pages": [
      {
        "path": "/",
        "sessions": 982,
        "share": 0.495
      },
      {
        "path": "/pricing",
        "sessions": 312,
        "share": 0.157
      }
    ],
    "exit_pages": [
      {
        "path": "/pricing",
        "sessions": 534,
        "share": 0.269
      },
      {
        "path": "/blog",
        "sessions": 289,
        "share": 0.146
      }
    ]
  }
}
```

### Notes

* `share` represents the fraction of total sessions for each entry or exit page.
* Entry pages indicate where visitors first land; exit pages indicate the last page viewed before leaving.

***

## Filter Options

```
GET /properties/{propertyId}/filters
```

Lists the values you can pass as dimension filters for a date range: pages (all, entry, exit), devices, browsers, countries, regions, referrers and UTM values. `start` and `end` are optional here (default: the last 30 days, maximum 1 year).

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/filters?start=2024-05-01&end=2024-05-31"
```

### Sample Response

```json
{
  "meta": { "property_id": "PROPERTY_ID", "start": "2024-05-01T00:00:00.000Z", "end": "2024-05-31T00:00:00.000Z", "timezone": "UTC" },
  "data": {
    "pages": { "all": ["/", "/pricing"], "entry": ["/"], "exit": ["/pricing"] },
    "devices": { "os": ["macOS", "iOS", "Windows"], "types": ["desktop", "mobile"] },
    "browsers": ["chrome", "safari"],
    "countries": ["US", "GB"],
    "regions": ["California", "England"],
    "referrers": ["google", "direct"],
    "utm": { "sources": ["google"], "mediums": ["cpc"], "campaigns": ["spring_launch"], "contents": [], "terms": [], "ids": [] }
  }
}
```

***

## Pages Breakdown

```
GET /properties/{propertyId}/pages/breakdown
```

Returns performance metrics for all pages, including views, unique visitors, average scroll depth, and bounce rate.

### Query Parameters

| Name     | Type   | Required | Default | Notes                                                     |
| -------- | ------ | -------- | ------- | --------------------------------------------------------- |
| `limit`  | number | No       | 50      | Maximum entries to return (maximum supported value: 100). |
| `offset` | number | No       | 0       | Rows to skip, for pagination.                             |
| `search` | string | No       | N/A     | Only pages whose path contains this text.                 |

### Sample Request

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

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "timezone": "UTC",
    "limit": 20
  },
  "data": [
    {
      "path": "/",
      "page_views": 3245,
      "unique_visitors": 2108,
      "avg_scroll_depth": 0.62,
      "bounce_rate": 0.38
    },
    {
      "path": "/pricing",
      "page_views": 1823,
      "unique_visitors": 1456,
      "avg_scroll_depth": 0.74,
      "bounce_rate": 0.29
    }
  ]
}
```

### Notes

* `avg_scroll_depth` is a decimal representing the average percentage of the page scrolled (e.g. `0.62` = 62%).
* `bounce_rate` is page-level, not site-level.
* Results are sorted by `page_views` in descending order by default.

***

## Pages Details

```
GET /properties/{propertyId}/pages/details
```

Returns a deep dive for a single page, including UTM attribution, device breakdown, and country breakdown.

### Query Parameters

| Name        | Type   | Required | Default | Notes                                           |
| ----------- | ------ | -------- | ------- | ----------------------------------------------- |
| `page`      | string | Yes      | N/A     | The page path to get details for (URL-encoded). |
| `limit`     | number | No       | 20      | Maximum entries per breakdown (maximum: 50).    |
| `utm_limit` | number | No       | 20      | Maximum UTM rows (maximum: 50).                 |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/pages/details?page=%2Fpricing&start=2024-05-01&end=2024-05-31&timezone=UTC"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "page": "/pricing",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "timezone": "UTC"
  },
  "data": {
    "page_views": 1823,
    "unique_visitors": 1456,
    "avg_scroll_depth": 0.74,
    "bounce_rate": 0.29,
    "utm": [
      {
        "source": "google",
        "medium": "cpc",
        "campaign": "spring_launch",
        "page_views": 412,
        "share": 0.226
      }
    ],
    "devices": [
      {
        "device": "desktop",
        "page_views": 1102,
        "share": 0.604
      }
    ],
    "countries": [
      {
        "country": "US",
        "page_views": 845,
        "share": 0.463
      }
    ]
  }
}
```

### Notes

* Use URL encoding for the `page` parameter (e.g. `/pricing page` becomes `%2Fpricing%20page`).
* Breakdowns (UTM, devices, countries) are specific to the requested page.
* Combines aggregate page metrics with dimensional breakdowns in a single response.

***

## 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       | 50      | Maximum entries to return (maximum supported value: 100). |
| `offset`      | number | No       | 0       | Rows to skip, for pagination.                             |
| `search`      | string | No       | N/A     | Only click targets whose name contains this text.         |

### Sample Request

```bash
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

```json
{
  "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       | 20      | Maximum entries to return (maximum: 50).             |
| `offset`      | number | No       | 0       | Rows to skip, for pagination.                        |

### Sample Request

```bash
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

```json
{
  "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       | 50      | Maximum entries to return (maximum supported value: 100). |
| `offset`      | number | No       | 0       | Rows to skip, for pagination.                             |
| `search`      | string | No       | N/A     | Only form targets whose name contains this text.          |

### Sample Request

```bash
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

```json
{
  "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`** (per row or trend bucket) and **`summary.total_unique_submissions`** are the documented field names for deduplicated form counts — each distinct session that submitted a form, counted once.
* Some live responses still emit the legacy alias **`unique_sessions`** (and **`summary.unique_sessions`**) with the same numeric value. Treat either name as the unique count; prefer the documented keys when both are present.
* **`submissions`** / **`total_submissions`** count every form submit event and are always greater than or equal to the unique counts when visitors resubmit.

***

## 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       | 20      | Maximum entries to return (maximum: 50).            |
| `offset`      | number | No       | 0       | Rows to skip, for pagination.                       |

### Sample Request

```bash
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

```json
{
  "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.
* Each form row includes **`unique_submissions`** (documented) and may also include **`unique_sessions`** (legacy alias) with the same value. **`summary.total_unique_submissions`** is the documented period total; **`summary.unique_sessions`** is the legacy alias.

***

## Heatmap

```
GET /properties/{propertyId}/heatmap
```

Summarizes click and scroll heatmap data for one page: which elements get the clicks, on which device, and where visitors stop scrolling.

### Query Parameters

| Name       | Type   | Required | Default | Notes                                           |
| ---------- | ------ | -------- | ------- | ----------------------------------------------- |
| `page`     | string | Yes      | N/A     | Page path, starting with `/` (e.g. `/pricing`). |
| `period`   | enum   | No       | `7d`    | `24h`, `7d`, `30d` or `90d`.                    |
| `device`   | enum   | No       | N/A     | `desktop` or `mobile`. Omit for both.           |
| `limit`    | number | No       | 15      | Top elements to return (1–50).                  |
| `timezone` | string | No       | `UTC`   | IANA zone name.                                 |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/heatmap?page=/pricing&period=30d&limit=10"
```

### Sample Response

```json
{
  "propertyId": "PROPERTY_ID",
  "page": "/pricing",
  "period": "30d",
  "device": null,
  "clicks": {
    "total": 1840,
    "byDevice": {
      "desktop": { "clicks": 1210, "sharePercent": 65.8 },
      "mobile": { "clicks": 630, "sharePercent": 34.2 }
    },
    "unlabeled": { "clicks": 120, "sharePercent": 6.5 },
    "topElements": [
      { "selector": "button.hero-cta", "text": "Start free", "clicks": 412, "desktopClicks": 300, "mobileClicks": 112, "sharePercent": 22.4 }
    ]
  },
  "scroll": {
    "visitors": 2960,
    "averageScrollPercent": 58.2,
    "reach": [{ "depthPercent": 25, "reachedPercent": 91.0 }, { "depthPercent": 50, "reachedPercent": 62.5 }],
    "biggestDrop": { "fromDepthPercent": 40, "toDepthPercent": 50, "dropPercent": 18.3 }
  }
}
```

### Notes

* `scroll` is `null` when no scroll-depth data exists for the page in the period.
* `unlabeled` counts clicks on elements Humblytics could not name.

***

## Funnels

```
GET /properties/{propertyId}/funnels
```

Runs a funnel query across a defined sequence of steps, returning conversion rates between each step.

### Query Parameters

| Name           | Type   | Required | Default      | Notes                                                                                                                                                                     |
| -------------- | ------ | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `steps`        | JSON   | Yes      | N/A          | URL-encoded JSON array of 2–20 step definitions (see below).                                                                                                              |
| `mode`         | enum   | No       | `sequential` | `sequential` (steps must occur in order) or `unbounded` (steps in any order).                                                                                             |
| `breakdown_by` | enum   | No       | N/A          | Break results down by one of `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_id`, `utm_term`, `device`, `os`, `browser`, `referrer`, `region`, `country`. |
| `limit`        | number | No       | 10           | Rows per breakdown value (maximum 50). Only with `breakdown_by`.                                                                                                          |

The date range may span at most 400 days.

### Step definition

Each step has a `name` and one or more `conditions` (at most 10). A session satisfies a step when any of its conditions match.

| Field                       | Type   | Required        | Notes                                                                                                                                                                         |
| --------------------------- | ------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                      | string | Yes             | Label shown in the response.                                                                                                                                                  |
| `conditions[]`              | array  | Yes             | 1–10 conditions.                                                                                                                                                              |
| `conditions[].type`         | enum   | Yes             | `page_view` or `event`.                                                                                                                                                       |
| `conditions[].path`         | string | For `page_view` | Page path. `*` is a wildcard (e.g. `/blog/*`).                                                                                                                                |
| `conditions[].action`       | enum   | For `event`     | `click`, `form_submission` or `revenue`.                                                                                                                                      |
| `conditions[].target`       | string | No              | Narrow an event to one click or form target.                                                                                                                                  |
| `conditions[].utm_source` … | string | No              | Any of `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_id`, `utm_term`, `device`, `os`, `browser`, `referrer`, `region`, `country` to restrict the condition. |
| `property_id`               | string | No              | Count this step on another site you own (cross-site funnels).                                                                                                                 |
| `min_delay`, `max_delay`    | number | No              | Seconds that must (or may at most) pass since the previous step.                                                                                                              |

```json
[
  { "name": "Homepage", "conditions": [{ "type": "page_view", "path": "/" }] },
  { "name": "Pricing", "conditions": [{ "type": "page_view", "path": "/pricing" }] },
  { "name": "Signed up", "conditions": [{ "type": "event", "action": "form_submission" }] }
]
```

### Sample Request

```bash
STEPS='[{"name":"Homepage","conditions":[{"type":"page_view","path":"/"}]},{"name":"Pricing","conditions":[{"type":"page_view","path":"/pricing"}]},{"name":"Signed up","conditions":[{"type":"event","action":"form_submission"}]}]'
curl -G \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  --data-urlencode "steps=$STEPS" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/funnels?start=2024-05-01&end=2024-05-31&timezone=UTC&mode=sequential"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "timezone": "UTC",
    "mode": "sequential",
    "step_count": 3
  },
  "data": {
    "steps": [
      { "step_index": 0, "step_name": "Homepage", "total_sessions": 3142, "total_events": 4010, "drop_off_count": 1886, "drop_off_rate": 0.6, "conversion_rate": 1.0, "avg_time_from_previous": null, "median_time_from_previous": null },
      { "step_index": 1, "step_name": "Pricing", "total_sessions": 1256, "total_events": 1402, "drop_off_count": 942, "drop_off_rate": 0.75, "conversion_rate": 0.4, "avg_time_from_previous": 84.2, "median_time_from_previous": 41.0 },
      { "step_index": 2, "step_name": "Signed up", "total_sessions": 314, "total_events": 320, "drop_off_count": 0, "drop_off_rate": 0, "conversion_rate": 0.1, "avg_time_from_previous": 120.5, "median_time_from_previous": 66.0 }
    ]
  },
  "summary": {
    "total_entered": 3142,
    "total_completed": 314,
    "overall_conversion_rate": 0.1,
    "avg_completion_time": 204.7
  }
}
```

### Notes

* `conversion_rate` at each step is relative to step 1 (sessions that entered the funnel). `drop_off_rate` is the share of that step's sessions that did not reach the next step.
* With `breakdown_by`, the response also carries a `breakdown` object with the same step metrics per dimension value.
* Malformed steps return `400 invalid_steps` with a message naming the step and field.
* Use `mode=sequential` when order matters (e.g. homepage → pricing → signup). Use `unbounded` for unordered funnels.

***

## Funnels Sankey

```
GET /properties/{propertyId}/funnels/sankey
```

Returns path flow data for a funnel in a Sankey diagram format, showing how sessions move between steps.

### Query Parameters

Accepts all the same parameters as the `/funnels` endpoint, plus:

| Name           | Type   | Required | Default | Notes                                            |
| -------------- | ------ | -------- | ------- | ------------------------------------------------ |
| `max_paths`    | number | No       | 100     | Maximum number of links to return (maximum 500). |
| `min_sessions` | number | No       | 1       | Minimum sessions a link must have to appear.     |

### Sample Request

```bash
curl -G \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  --data-urlencode "steps=$STEPS" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/funnels/sankey?start=2024-05-01&end=2024-05-31&timezone=UTC&max_paths=10&min_sessions=5"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "timezone": "UTC",
    "step_count": 3,
    "total_paths": 4
  },
  "data": {
    "nodes": [
      { "id": "step_0_cond_0", "step_index": 0, "label": "Homepage", "total_sessions": 3142 },
      { "id": "step_1_cond_0", "step_index": 1, "label": "Pricing", "total_sessions": 1256 },
      { "id": "step_2_cond_0", "step_index": 2, "label": "Signed up", "total_sessions": 314 }
    ],
    "links": [
      { "source": "step_0_cond_0", "target": "step_1_cond_0", "value": 1256, "avg_time": 84.2 },
      { "source": "step_1_cond_0", "target": "step_2_cond_0", "value": 314, "avg_time": 120.5 }
    ]
  },
  "summary": {
    "total_sessions": 3142,
    "completed_sessions": 314,
    "drop_off_sessions": 2828
  }
}
```

### Notes

* There is one node per step condition (`step_<step>_cond_<condition>`), so a step with several conditions shows which path visitors took. Sessions that left the funnel are counted in `summary.drop_off_sessions`.
* Use `max_paths` and `min_sessions` to control the granularity of the output.
* Useful for visualizing where users leave the funnel and which alternative paths they take.

***

## Funnels Suggestions

```
GET /properties/{propertyId}/funnels/suggestions
```

Returns the pages, click targets, form targets and conversion events seen on the site in a date range, with counts — the building blocks for funnel steps.

### Query Parameters

| Name           | Type   | Required | Default      | Notes                                        |
| -------------- | ------ | -------- | ------------ | -------------------------------------------- |
| `start`, `end` | string | No       | Last 30 days | ISO-8601 dates.                              |
| `timezone`     | string | No       | `UTC`        | IANA zone name.                              |
| `search`       | string | No       | N/A          | Only pages and targets containing this text. |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/funnels/suggestions?search=pricing"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-04-07T00:00:00.000Z",
    "end": "2024-05-08T00:00:00.000Z"
  },
  "data": {
    "pages": [{ "path": "/pricing", "page_views": 1823, "unique_sessions": 1456 }],
    "clicks": [{ "target": "Start free", "secondary": "button.hero-cta", "event_count": 412 }],
    "form_submissions": [{ "target": "Contact Form", "secondary": null, "event_count": 89 }],
    "conversions": [{ "action": "revenue", "event_count": 31 }]
  }
}
```

### Notes

* Suggestions are based on your actual traffic data.
* Map a page to `{ "type": "page_view", "path": … }` and a click or form to `{ "type": "event", "action": …, "target": … }` when building `steps`.

***

## Saved Funnels

### List Saved Funnels

```
GET /properties/{propertyId}/saved-funnels
```

Returns all saved funnel configurations for the property.

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/saved-funnels"
```

### Sample Response

```json
{
  "funnels": [
    {
      "funnel_id": "9b7c1e2a-…",
      "property_id": "PROPERTY_ID",
      "name": "Homepage to Signup",
      "steps": [
        { "name": "Homepage", "conditions": [{ "type": "page_view", "path": "/" }] },
        { "name": "Pricing", "conditions": [{ "type": "page_view", "path": "/pricing" }] },
        { "name": "Signed up", "conditions": [{ "type": "event", "action": "form_submission" }] }
      ],
      "created_at": "2024-05-01T10:00:00.000Z",
      "updated_at": "2024-05-01T10:00:00.000Z"
    }
  ]
}
```

### Create or Update a Saved Funnel

```
POST /properties/{propertyId}/saved-funnels
```

Creates a new saved funnel configuration. Include `id` in the body to update an existing funnel.

### Request Body

| Field   | Type   | Required | Notes                                                                   |
| ------- | ------ | -------- | ----------------------------------------------------------------------- |
| `id`    | string | No       | Include to update an existing saved funnel.                             |
| `name`  | string | Yes      | A descriptive name for the funnel (up to 200 characters).               |
| `steps` | array  | Yes      | Step definitions in the same shape as the `/funnels` `steps` parameter. |

### Sample Request

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Homepage to Signup",
    "steps": [
      { "name": "Homepage", "conditions": [{ "type": "page_view", "path": "/" }] },
      { "name": "Pricing", "conditions": [{ "type": "page_view", "path": "/pricing" }] },
      { "name": "Signed up", "conditions": [{ "type": "event", "action": "form_submission" }] }
    ]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/saved-funnels"
```

### Sample Response (201 Created; 200 on update)

```json
{
  "funnel": {
    "funnel_id": "9b7c1e2a-…",
    "property_id": "PROPERTY_ID",
    "name": "Homepage to Signup",
    "steps": [ { "name": "Homepage", "conditions": [{ "type": "page_view", "path": "/" }] } ],
    "created_at": "2024-05-01T10:00:00.000Z",
    "updated_at": "2024-05-01T10:00:00.000Z"
  }
}
```

### Delete a Saved Funnel

```
DELETE /properties/{propertyId}/saved-funnels/{funnelId}
```

Deletes a saved funnel configuration. Returns `{ "ok": true }`, or `404 not_found`.

### Sample Request

```bash
curl -X DELETE \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/saved-funnels/9b7c1e2a-…"
```

### Notes

* Deleting a saved funnel does not affect historical funnel query results.
* Saved funnels are property-scoped — they are visible to all API keys for the same property.
* Creating a funnel beyond your plan's saved-funnel limit returns `402` with `{ "error": "plan_limit_reached", "limit", "current" }`.

***

## Attribution

```
GET /properties/{propertyId}/attribution/first-touch
GET /properties/{propertyId}/attribution/last-touch
```

Credits conversions to the first (or last) UTM source, medium, campaign and referrer group of the converting session's history. Accepts `start`, `end`, `timezone` and `granularity` like `/traffic/trends`, plus:

| Name               | Type   | Required | Default   | Notes                                                                              |
| ------------------ | ------ | -------- | --------- | ---------------------------------------------------------------------------------- |
| `conversion_event` | string | No       | `revenue` | The event that counts as a conversion, e.g. `revenue`, `form_submission`, `click`. |

### Sample Request

```bash
curl \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/PROPERTY_ID/attribution/first-touch?start=2024-05-01&end=2024-05-31&conversion_event=form_submission"
```

### Sample Response

```json
{
  "meta": {
    "property_id": "PROPERTY_ID",
    "start": "2024-05-01T00:00:00.000Z",
    "end": "2024-05-31T23:59:59.000Z",
    "conversion_event": "form_submission",
    "model": "first_touch"
  },
  "data": [
    { "source": "google", "medium": "cpc", "campaign": "spring_launch", "referrer_group": "search", "conversions": 48 },
    { "source": "direct", "medium": "none", "campaign": "none", "referrer_group": "direct", "conversions": 31 }
  ]
}
```

### Notes

* Up to 100 rows, sorted by `conversions`. Sessions with no UTM values are reported as `direct` / `none`.
* For ad-spend and ROAS by campaign, see the [Ads Attribution API](https://docs.humblytics.com/ads-attribution-api.md).

***

## Multi-Property Aggregate

These `POST` endpoints let you query data across multiple properties in a single request. Send a JSON body with `{ "propertyIds": [...] }` along with the same query parameters used by the corresponding single-property endpoints.

All aggregate endpoints require the API key to have access to every property listed in the request (an account key, or a property key for exactly that one property).

| Endpoint                                              | Description                                        |
| ----------------------------------------------------- | -------------------------------------------------- |
| `POST /properties/aggregate/traffic/trends`           | Aggregate traffic trends across properties.        |
| `POST /properties/aggregate/traffic/summary`          | Aggregate traffic summary across properties.       |
| `POST /properties/aggregate/traffic/breakdown`        | Aggregate traffic breakdowns across properties.    |
| `POST /properties/aggregate/traffic/realtime`         | Aggregate realtime visitor data across properties. |
| `POST /properties/aggregate/traffic/entry-exit-pages` | Aggregate entry/exit pages across properties.      |
| `POST /properties/aggregate/pages/breakdown`          | Aggregate page performance across properties.      |
| `POST /properties/aggregate/clicks/breakdown`         | Aggregate click data across properties.            |
| `POST /properties/aggregate/forms/breakdown`          | Aggregate form submission data across properties.  |

### Sample Request

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyIds": ["prop_abc123", "prop_def456"]
  }' \
  "https://app.humblytics.com/api/external/v1/properties/aggregate/traffic/summary?start=2024-05-01&end=2024-05-31&timezone=UTC"
```

### Notes

* Response format matches the corresponding single-property endpoint, with data aggregated across all specified properties.
* The `meta` object will include a `property_ids` array instead of a single `property_id`.
* The realtime aggregate endpoint does not require date parameters, same as the single-property version.

***

## Account, Sites and Billing

These endpoints let an agent do what the onboarding wizard does: read the plan and data-point balance, add a site, fetch the tracking snippet, confirm the install, and buy data points. They need an **account key** — a property key answers `403 account_key_required`. (`GET /properties/{propertyId}/install` and `POST …/setup-report` also accept a property key for that site.)

### Account

```
GET /account
```

```bash
curl -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/account"
```

```json
{
  "plan": { "id": "FREE_START", "source": "free_start" },
  "planKind": "free_start",
  "dataPoints": { "included": 5000, "topUp": 0, "limit": 5000, "used": 1240, "remaining": 3760, "status": "normal", "periodStart": "2026-11-01T00:00:00.000Z", "periodEnd": "2027-11-01T00:00:00.000Z" },
  "topUpBalance": { "points": 0, "blocks": [] },
  "sitesLimit": 1,
  "seatsLimit": 1,
  "agentsCheckout": { "available": true, "eligible": true },
  "topUps": { "available": true, "eligible": false, "blockPoints": 100000, "maxBlocks": 10 },
  "autoTopUp": { "available": false, "enabled": false, "maxPerPeriod": 3 },
  "requestsMetered": false,
  "properties": [
    { "propertyId": "PROPERTY_ID", "domain": "example.com", "name": "example.com", "scriptId": "SCRIPT_ID" }
  ]
}
```

`dataPoints.status` is `normal`, `approaching_limit`, `past_limit`, `paused` or `payment_failed`. On Free start, tracking pauses when the 5,000 included data points are used; the Agents plan ($39 one time) adds 100,000 data points for 12 months and unlimited sites, and top-ups cost $29 per 100,000.

`GET /api/v2/properties` (note: outside `/api/external/v1`) also lists the sites a key can reach, as `{ "properties": [{ "propertyId", "domain", "name" }] }`.

### Add a site

```
POST /properties
```

| Field    | Type   | Required | Notes                                 |
| -------- | ------ | -------- | ------------------------------------- |
| `domain` | string | Yes      | e.g. `example.com`.                   |
| `name`   | string | No       | Display name. Defaults to the domain. |

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }' \
  "https://app.humblytics.com/api/external/v1/properties"
```

```json
{
  "property": { "propertyId": "PROPERTY_ID", "domain": "example.com", "name": "example.com" },
  "existing": false,
  "restored": false,
  "scriptId": "SCRIPT_ID",
  "snippet": "<script async src=\"https://app.humblytics.com/hmbl.min.js?id=SCRIPT_ID\"></script>",
  "reachability": { "reachable": true, "httpStatus": 200, "checkedUrl": "https://example.com/" }
}
```

* `201` for a new site, `200` with `existing: true` when the domain is already on the account (or `restored: true` when it was archived).
* `400 invalid_domain` when the domain is not usable.
* `402 site_limit_reached` when the plan's site limit is reached. On Free start (1 site) the error's `details.upgrade` points to `POST /billing/agents-checkout`.

### Delete a site

```
DELETE /properties/{propertyId}
```

Archives the site, the same as **Site settings → Danger zone**: it drops out of lists and site-limit counts, historical data is kept, and adding the same domain again restores it. Returns `{ "property": { … }, "deleted": true }`, or `404 not_found` for a site you do not own.

### Install status

```
GET /properties/{propertyId}/install?path=/
```

Checks whether the tracking script is on the site and whether data has arrived. `path` (optional) picks the page to check.

```json
{
  "propertyId": "PROPERTY_ID",
  "domain": "example.com",
  "status": "installed_waiting_for_first_pageview",
  "scriptId": "SCRIPT_ID",
  "snippet": "<script async src=\"https://app.humblytics.com/hmbl.min.js?id=SCRIPT_ID\"></script>",
  "check": { "reachable": true, "httpStatus": 200, "checkedUrl": "https://example.com/", "scriptFound": true, "foundVia": "html" },
  "platform": "webflow",
  "connectors": [],
  "activity": { "firstPageviewAt": null }
}
```

`status` is one of `live` (data arrived), `installed_waiting_for_first_pageview`, `not_installed` or `site_unreachable`. `platform` is the detected site builder when Humblytics can tell, so an agent can pick the right install guide.

### Report a setup outcome

```
POST /properties/{propertyId}/setup-report
```

Tells the app what the agent could not do on the person's site, so the **Setting up** screen says it instead of waiting.

| Field      | Type   | Required | Notes                                                                                                            |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `outcome`  | enum   | Yes      | `publish_declined` (the person said no to publishing) or `cannot_install` (no way to add code on this platform). |
| `platform` | string | No       | Up to 60 characters.                                                                                             |
| `detail`   | string | No       | Up to 300 characters.                                                                                            |

Returns `201` with the stored report (`outcome`, `platform`, `detail`, `reportedAt`).

### Billing

| Endpoint                        | Body                                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /billing/agents-checkout` | —                                        | Returns `{ "url", "sessionId" }` — a Stripe Checkout link for the Agents plan ($39 one time). The person pays in a browser. `409 already_subscribed` on an account that already has a plan.                                                                                                                                                                                                                   |
| `POST /billing/top-up`          | `{ "blocks": 1 }`                        | Charges the saved card for `blocks` × 100,000 data points at $29 each (1–10 blocks). Send an `Idempotency-Key` header to make retries safe. Returns `{ "topUpId", "blocks", "points", "amountCents", "currency", "limit", "expiresAt" }`. `400 not_api_plan` outside the Agents plan; `402 requires_action` when the bank wants the cardholder to approve — the person tops up from Account settings instead. |
| `PUT /billing/auto-top-up`      | `{ "enabled": true, "maxPerPeriod": 3 }` | Turns automatic top-ups on or off. `maxPerPeriod` caps blocks per month (1–20, default 3). `400 no_payment_method` when no card is saved.                                                                                                                                                                                                                                                                     |

```bash
curl -X POST \
  -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f1c0a8e-top-up-1" \
  -d '{ "blocks": 1 }' \
  "https://app.humblytics.com/api/external/v1/billing/top-up"
```

Billing errors use the standard error envelope with the codes above (for example `{ "error": { "code": "not_api_plan", "message": "…" } }`).

***

## Errors

| Status | Code                              | When it happens                                                                                     |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request`                 | Bad dates, unsupported timezone or granularity, ranges that are too large, missing required fields. |
| `400`  | `invalid_steps`                   | A funnel `steps` definition is malformed (wrong count, missing `name`, bad condition).              |
| `400`  | `invalid_domain`                  | `POST /properties` received a domain that is not usable.                                            |
| `401`  | `unauthorized`                    | Missing or invalid API key header.                                                                  |
| `402`  | `site_limit_reached`              | The plan's site limit is reached.                                                                   |
| `403`  | `forbidden`                       | Property ID does not match the API key or the key does not have `metrics` permission.               |
| `403`  | `account_key_required`            | An account, site-setup or billing endpoint was called with a property key.                          |
| `404`  | `not_found`                       | The site, funnel or experiment does not exist (or is not yours).                                    |
| `500`  | `internal_error`                  | Unexpected server error. Retry later or contact support.                                            |
| `503`  | `service_unavailable`             | An AI or screenshot service is not available right now.                                             |
| `503`  | `subscription_status_unavailable` | Subscription status could not be read. Retry shortly.                                               |

Error payloads follow this structure:

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

There is no general request rate limit on analytics endpoints. Split-test recommendations are the one rate-limited call; see the [Split Testing API](https://docs.humblytics.com/split-testing-api.md#errors) for its `429` shape. Plan-limit errors from saved funnels and split tests use a flat `{ "error": "plan_limit_reached", "limit", "current" }` body.

***

## 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.
* Use the **Multi-Property Aggregate** endpoints to consolidate reporting across multiple sites without making separate requests per property.
* Save frequently-used funnel definitions with the **Saved Funnels** endpoints so they can be re-run without redefining steps each time.
* **Looking for A/B testing endpoints?** See the [Split Testing API](https://docs.humblytics.com/split-testing-api.md) to get AI-powered test recommendations, create no-code experiments, and manage running tests programmatically.
