# Open API Documentation

***

## 1. General Conventions

### 1.1 Overview

The Ptengine Open API provides RESTful endpoints for programmatic access to heatmap and analytics data. You can hand this document to an AI Agent — the agent reads natural-language requests, builds the right query, and calls the API directly.

**Base URL:**

```
https://xbackend.ptengine.com/
```

### 1.2 Authentication

All requests must include the `x-api-key` header with your API Key.

```
x-api-key: pt-your-api-key-here
```

**How to get an API Key:**

> **Permission:** Only Admin and Owner roles can create and manage API Keys.

1. Log in to Ptengine
2. Open the Experience module
3. Click the settings icon (⚙) in the top-right and choose "External App Integration"
4. Switch to the "API Keys" tab
5. Click "Create API Key", enter a name and choose the permission scope (data upload / data query)
6. Copy and store the key safely (it is shown only once)

### 1.3 Rate Limits

Limits vary by plan:

| Plan       | RPM (per minute) | RPD (per day) |
| ---------- | ---------------- | ------------- |
| Free       | 3                | 100           |
| Free Trial | 10               | 1,000         |
| Growth     | 30               | 3,000         |

Rate-limit info is returned via response headers:

```
X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 28
X-RateLimit-Limit-Day: 3000
X-RateLimit-Remaining-Day: 2997
X-RateLimit-Tier: GROWTH
```

### 1.4 Response Format

All endpoints return JSON in a uniform wrapper:

* Success (HTTP 200): `{ "code": 200, "message": "OK", "data": ... }`
* Failure (HTTP 4xx): `{ "code": 4xxx, "message": "..." }`

See [Appendix — Error Codes](#error-codes) for the full list.

***

## 2. Insight

This chapter covers four query endpoints: Heatmap, Event, Data Center, and Conversion.

### 2.1 Common Rules

All four endpoints share two request fields: `conversionNames` and `filters`. Where to look up conversion goal names; how to write `filters` and where to find the values inside them — all covered here. Read this first, then each endpoint chapter is ready to use.

#### Conversion Goals

When querying conversion data (e.g. "how many purchases completed", "what's the signup conversion rate"), you need to tell the system which conversion goal to query. This endpoint returns all goal names configured in Ptengine — copy a name into your query request.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/goals \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "conversions": [
            { "id": "1753350579776", "name": "ptmind signup" },
            { "id": "1753350579999", "name": "Purchase complete" }
        ]
    }
}
```

After getting `name`, write it into the `conversionNames` field of any query endpoint (`/event/query`, `/datacenter/query`, `/conversion/query`, `/heatmap/query`) to query data for that goal. For example: `"conversionNames": ["Purchase complete"]`.

#### Filter

Add conditions to the `filters` field of your request body to narrow the data scope. For example: Mobile only, Japan only, a specific campaign source only.

```json
{ "name": "country", "op": "include", "value": ["Japan"] }
```

Fields:

| Field   | Meaning                                                           |
| ------- | ----------------------------------------------------------------- |
| `name`  | The field to filter on (see the categories below)                 |
| `op`    | `include` or `exclude`; no other operators                        |
| `value` | The value(s), must be an array (even a single value: `["Japan"]`) |

> Custom-property filters (filter by event property) need extra `eventName` / `eventVariant` fields — see "Custom-property filter (advanced)" below.

Fields fall into two categories:

**Fixed-value fields**

The four fields below accept fixed enumerated values — copy them verbatim:

| name         | Meaning     | Allowed values                                                   |
| ------------ | ----------- | ---------------------------------------------------------------- |
| `deviceType` | Device Type | `PC`, `Mobile`, `Tablet`                                         |
| `sourceType` | Source Type | `Direct`, `Search`, `Social`, `Referral`, `Campaign`, `AISearch` |
| `visitType`  | Visit Type  | `New visits`, `Returning visits`                                 |
| `exitType`   | Exit Type   | `Bounce visits`, `Non-bounce visits`                             |

**Dynamic-value fields**

Values vary by data. Query them via the [filter-values](#filter-values) endpoint below.

| Category   | name               | Meaning                        | value example                                                |
| ---------- | ------------------ | ------------------------------ | ------------------------------------------------------------ |
| Device     | `os`               | Operating system               | `["Windows", "Mac OS X"]`                                    |
| Device     | `osVersion`        | OS version                     | `["Windows 10", "Mac OS X 10.15.7", "iOS 17.0"]`             |
| Device     | `browser`          | Browser                        | `["Chrome", "Mobile Safari", "Edge"]`                        |
| Device     | `browserVersion`   | Browser version                | `["Chrome 124.0.0", "Edge 146.0.0", "Mobile Safari 13.0.3"]` |
| Device     | `screenResolution` | Screen resolution              | `["1920x1080", "1440x900"]`                                  |
| Device     | `deviceBrand`      | Device brand                   | `["Apple", "Samsung"]`                                       |
| Geo        | `country`          | Country / Area                 | `["Japan", "China", "United States"]`                        |
| Geo        | `region`           | State / Region                 | `["Tokyo", "Beijing", "Hong Kong"]`                          |
| Source     | `searchEngine`     | Search engine                  | `["google"]`                                                 |
| Source     | `socialNetwork`    | Social network                 | `["facebook"]`                                               |
| Source     | `socialUrl`        | Social URL                     | `["https://www.facebook.com/"]`                              |
| Source     | `aiName`           | AI search                      | `["ChatGPT", "Perplexity"]`                                  |
| Source     | `referralSource`   | Referral website               | `["www.muji.com"]`                                           |
| Source     | `referralUrl`      | Referral URL                   | `["https://www.muji.com/"]`                                  |
| Ad         | `campaignUrl`      | Campaign URL                   | `["https://www.google.com/"]`                                |
| Ad         | `utmCampaign`      | Campaign name                  | `["summer_sale"]`                                            |
| Ad         | `utmSource`        | Source (UTM)                   | `["google", "facebook"]`                                     |
| Ad         | `utmMedium`        | Medium (UTM)                   | `["cpc", "email"]`                                           |
| Ad         | `utmTerm`          | Term (UTM)                     | `["heatmap tool"]`                                           |
| Ad         | `utmContent`       | Content (UTM)                  | `["banner_a"]`                                               |
| Page       | `combinedPages`    | Entry page (combined)          | `["https://ptengine.jp/app/login"]`                          |
| Page       | `originalPages`    | Original pages (full URL)      | `["https://ptengine.jp/app/select_project?from=login"]`      |
| Event      | `eventName`        | Event name                     | `["checkout_completed", "product_viewed"]`                   |
| Event      | `dimension`        | Custom dimension (cross-event) | Requires `eventVariant`                                      |
| Event      | `eventDimension`   | Custom dimension (event-bound) | Requires `eventName` and `eventVariant`                      |
| Conversion | `conversionName`   | Conversion name                | `["Purchase complete"]`                                      |

> Value examples are illustrative. For actual available values, call the [filter-values](#filter-values) endpoint.

**Custom-property filter (advanced)**

Use this only when your events carry custom properties (e.g. the `purchase` event has a `price` property) and you want to filter by those values. Two forms:

* **Bound to a specific event**: `{ "name": "eventDimension", "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100"] }` — sessions where the `purchase` event has `price=100`
* **Cross-event lookup**: `{ "name": "dimension", "eventVariant": "price", "op": "include", "value": ["100"] }` — any event where `price=100`

**filter-values**

Returns the list of available values for a given filter field (e.g. all countries with data, all OS values, etc.). The returned values can be used **directly** as the `value` field of any query endpoint's filter.

**Request parameters**

| Param          | Required    | Type   | Description                                                                                                                                                          |
| -------------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | yes         | string | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `name`         | yes         | string | Filter field name, see [Dynamic-value fields](#dynamic-fields) above                                                                                                 |
| `startDate`    | no          | string | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`. Defaults to last 30 days                                                                                                   |
| `endDate`      | no          | string | End date: `YYYY-MM-DD` or `YYYY/MM/DD`. Defaults to last 30 days                                                                                                     |
| `search`       | no          | string | Fuzzy-search keyword                                                                                                                                                 |
| `eventName`    | conditional | string | Only when `name="eventDimension"` (see Example 5 step 2)                                                                                                             |
| `eventVariant` | conditional | string | Only when `name="eventDimension"` (see Example 5 step 2)                                                                                                             |

**Example 1: regular field (e.g. country / os / browser)**

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "country",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "country",
        "values": ["Japan", "China", "United States", "Singapore"]
    }
}
```

**Example 2: fuzzy search (`search`)**

To filter the values list by a keyword, pass `search`. For example, country names containing "Ja" (matches Japan, Jamaica, etc.):

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "country",
    "search": "Ja",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "country",
        "values": ["Japan", "Jamaica"]
    }
}
```

**Example 3: list all event names (`name="eventName"`)**

Returns all event names that have data under the profile.

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventName",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventName",
        "values": ["purchase", "add_to_cart", "gallery_item_impression"]
    }
}
```

**Example 4: list all custom event property names**

Returns all custom event property names under the profile.

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "dimension",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "dimension",
        "values": ["price", "currency", "qty", "category"]
    }
}
```

**Example 5: values of a property under a specific event (`eventDimension`, two steps)**

`eventDimension` requires two steps: first use `name="eventDimension"` to fetch the list of "event + property" pairs, then pass the chosen `eventName` + `eventVariant` to fetch actual values.

**Step 1 — list (event, property) pairs:**

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventDimension",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventDimension",
        "values": [
            { "eventName": "purchase", "eventVariant": "price" },
            { "eventName": "purchase", "eventVariant": "currency" },
            { "eventName": "add_to_cart", "eventVariant": "qty" }
        ]
    }
}
```

**Step 2 — pass the chosen eventName + eventVariant to fetch values:**

Request:

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventDimension",
    "eventName": "purchase",
    "eventVariant": "price",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

Response:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventDimension",
        "eventName": "purchase",
        "eventVariant": "price",
        "values": ["100", "200", "500"]
    }
}
```

***

### 2.2 Heatmap

Heatmap analytics — clicks and views on pages, blocks, and elements.

#### Request parameters

| Param             | Required    | Type      | Description                                                                                                                                                                                                                                 |
| ----------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`       | yes         | string    | Query type: `page_metrics` (page basic metrics), `page_insight` (page insight by dimension), `block_metrics` (block metrics), `element_metrics` (element metrics)                                                                           |
| `profileId`       | yes         | string    | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9`                                                                        |
| `url`             | yes         | string    | Target page URL                                                                                                                                                                                                                             |
| `startDate`       | yes         | string    | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                    |
| `endDate`         | yes         | string    | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                      |
| `deviceType`      | yes         | string    | Device filter, see [Device type rules](#device-type-rules)                                                                                                                                                                                  |
| `rangeType`       | no          | string    | URL matching mode. `MERGE_URL` (default) merges query params, ignoring URL differences; `URL` does exact match                                                                                                                              |
| `metrics`         | no          | string\[] | If omitted, returns all metrics; if passed, only the specified ones. See [Available metrics](#available-metrics)                                                                                                                            |
| `conversionNames` | no          | string\[] | Conversion name list, see §2.1 [Conversion Goals](#conversion-goals)                                                                                                                                                                        |
| `filters`         | no          | object\[] | Filter conditions, see §2.1 [Filter](#filter)                                                                                                                                                                                               |
| `lang`            | no          | string    | Language for labels: `EN` (default), `ZH`, `JP`. Invalid values fall back to `EN`                                                                                                                                                           |
| `funName`         | conditional | string    | Required when `queryType=page_insight`. Allowed: `terminalType` (device), `sourceType` (traffic source), `visitType` (new/returning), `aiName` (AI source), `utmCampaign`, `utmSource`, `utmMedium`, `utmTerm`, `utmContent`, `week`, `day` |

#### Query types

**`page_metrics` — Page basic metrics**

Returns traffic, behavior, and conversion metrics for a specified page.

**Device types:** `ALL`, `PC`, `MOBILE`, `TABLET`

**`metrics` parameter:** if omitted, returns all metrics; if passed, only those specified.

**Conversion queries:** All query types support conversion. Add `completions` (count) and/or `conversionRate` (rate) to `metrics` — they can be passed individually or together — and pass conversion names via `conversionNames`.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "visits", "bounceRate", "conversionRate"],
    "conversionNames": ["Purchase complete"],
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": {
            "pv": { "value": "15,234", "label": "Page Views (PV)", "description": "Number of times the page was viewed." },
            "uv": { "value": "8,721", "label": "Unique Visitors (UV)", "description": "Number of unique visitors who viewed the page." },
            "visits": { "value": "10,532", "label": "Visits", "description": "Number of visits that viewed the page." },
            "bounceRate": { "value": "45.23%", "label": "Bounce Rate", "description": "Percentage of visitors who entered through this page and left without visiting any other page." },
            "conversionRate": { "value": "2.22%", "label": "Conversion Rate", "description": "Percentage of visits that completed a conversion after viewing this page." }
        },
        "conversions": [
            {
                "conversionName": "Purchase complete",
                "conversionRate": { "value": "1.71%", "label": "Conversion Rate", "description": "Percentage of visits that completed a conversion after viewing this page." }
            }
        ]
    },
    "meta": {
        "queryType": "page_metrics",
        "profileId": "566d12f9",
        "url": "https://ptengine.jp",
        "dateRange": { "start": "2025-06-01", "end": "2025-06-30" },
        "deviceType": "ALL",
        "lang": "EN"
    }
}
```

> **Note:** `conversions` only returns the conversion metrics requested in `metrics`. The example above only has `conversionRate`, so `conversions` only contains that. To also return completion counts, add `completions` to `metrics`.

**`page_insight` — Page insight (grouped by dimension)**

Returns page metrics grouped by a specified dimension.

**Device types:** `ALL`, `PC`, `MOBILE`, `TABLET`

**Required:** `funName` (if `metrics` is omitted, returns all metrics)

**Allowed `funName` values:**

| funName        | Meaning                                           |
| -------------- | ------------------------------------------------- |
| `terminalType` | Group by device type (PC/Smart phone/Tablet)      |
| `sourceType`   | Group by source type (Direct/Search/Social/...)   |
| `visitType`    | Group by visit type (New visits/Returning visits) |
| `aiName`       | Group by AI name                                  |
| `utmCampaign`  | Group by UTM Campaign                             |
| `utmSource`    | Group by UTM Source                               |
| `utmMedium`    | Group by UTM Medium                               |
| `utmTerm`      | Group by UTM Term                                 |
| `utmContent`   | Group by UTM Content                              |
| `week`         | Group by week                                     |
| `day`          | Group by day                                      |

**Request example (group by device type):**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "page_insight",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "bounceRate"],
    "funName": "terminalType",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "insights": [
            {
                "name": "PC",
                "metrics": {
                    "pv": { "value": "8,500", "label": "Page Views (PV)", "description": "Number of times the page was viewed." },
                    "uv": { "value": "5,200", "label": "Unique Visitors (UV)", "description": "Number of unique visitors who viewed the page." },
                    "bounceRate": { "value": "38.00%", "label": "Bounce Rate", "description": "Percentage of visitors who entered through this page and left without visiting any other page." }
                },
                "conversions": []
            },
            {
                "name": "Mobile",
                "metrics": {
                    "pv": { "value": "5,800", "label": "Page Views (PV)", "description": "Number of times the page was viewed." },
                    "uv": { "value": "3,100", "label": "Unique Visitors (UV)", "description": "Number of unique visitors who viewed the page." },
                    "bounceRate": { "value": "55.00%", "label": "Bounce Rate", "description": "Percentage of visitors who entered through this page and left without visiting any other page." }
                },
                "conversions": []
            },
            {
                "name": "Tablet",
                "metrics": {
                    "pv": { "value": "934", "label": "Page Views (PV)", "description": "Number of times the page was viewed." },
                    "uv": { "value": "421", "label": "Unique Visitors (UV)", "description": "Number of unique visitors who viewed the page." },
                    "bounceRate": { "value": "42.15%", "label": "Bounce Rate", "description": "Percentage of visitors who entered through this page and left without visiting any other page." }
                },
                "conversions": []
            }
        ]
    }
}
```

**`block_metrics` — Block metrics**

Returns metrics and screenshot URLs for each block (section) on a page. Requires that the page has been scanned and blocks configured in the product.

**Device types:** Must be `PC`, `MOBILE`, or `TABLET`. **`ALL` is not supported.**

**`metrics` parameter:** optional. If omitted, returns all metrics; if passed, only those specified. `blockName` and `screenshotUrl` are always returned.

**Available metrics:** `impression`, `impressionRate`, `avgDuration`, `dropoff`, `dropoffRate`, `completions`, `conversionRate`

**stayTimeFilter:** optional, block dwell time filter (seconds), default 5 seconds.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "block_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "blocks": [
            {
                "blockName": "Hero banner",
                "screenshotUrl": "https://cdn.example.com/screenshot/block1.png",
                "metrics": {
                    "impression": { "value": "12,000", "label": "Impression", "description": "PVs where users started seeing the current block." },
                    "impressionRate": { "value": "95.00%", "label": "Impression Rate", "description": "Share of PVs where users started seeing the current block." },
                    "avgDuration": { "value": "5s", "label": "Avg. Dwell Time", "description": "Average dwell time on this block after users stop scrolling." },
                    "dropoff": { "value": "800", "label": "Dropoff", "description": "PVs that left the current block without clicking through or converting." },
                    "dropoffRate": { "value": "6.70%", "label": "Dropoff Rate", "description": "Share of PVs that left the current block." }
                },
                "conversions": []
            }
        ]
    }
}
```

**`element_metrics` — Element metrics**

Returns metrics for each tracked element on a page. Requires page scanning and element configuration in the product.

**Device types:** Must be `PC`, `MOBILE`, or `TABLET`. **`ALL` is not supported.**

**`metrics` parameter:** optional. If omitted, returns all metrics; if passed, only those specified. `elementName` is always returned.

**Available metrics:** `impression`, `impressionRate`, `click`, `clickRate`, `completions`, `conversionRate`

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "element_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "elements": [
            {
                "elementName": "Signup button",
                "metrics": {
                    "impression": { "value": "10,500", "label": "Impression", "description": "PVs where users saw the current element." },
                    "impressionRate": { "value": "88.00%", "label": "Impression Rate", "description": "Share of PVs where users saw the current element." },
                    "click": { "value": "1,500", "label": "Click", "description": "Number of clicks on the current element." },
                    "clickRate": { "value": "14.30%", "label": "Click Rate", "description": "Clicks ÷ impressions." }
                },
                "conversions": []
            }
        ]
    }
}
```

#### Available metrics

**Page metrics (for `page_metrics` and `page_insight`)**

Use the field names below in the `metrics` array.

#### Traffic

| Field           | Description                                           | Type  |
| --------------- | ----------------------------------------------------- | ----- |
| `visits`        | Number of visits that viewed the page                 | value |
| `pv`            | Number of times the page was viewed                   | value |
| `uv`            | Number of unique visitors who viewed the page         | value |
| `newVisitsRate` | Percentage of new visits that viewed the page         | rate  |
| `entrances`     | Number of visits where this page was the landing page | value |

#### Behavior

| Field          | Description                                                                                                     | Type    |
| -------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| `fvRate`       | Percentage of visitors who didn't scroll, convert, or navigate after entering. High value = hero doesn't engage | rate    |
| `timeOnPage`   | Average time spent on the page. Measures how long content keeps visitors engaged                                | time    |
| `clicks`       | Total clicks on the page, regardless of whether the target is a link                                            | value   |
| `clickRate`    | Clicks per PV. Use it to gauge engagement                                                                       | rate    |
| `ctaClicks`    | Clicks on key CTAs on the page. Set key elements as CTAs in the heatmap                                         | value   |
| `ctaClickRate` | CTA click rate = CTA clicks / PV                                                                                | rate    |
| `bounceRate`   | Percentage of visitors who entered through this page and left without visiting any other page                   | rate    |
| `avgPageViews` | Average number of pages viewed by visitors who landed on this page                                              | decimal |

#### Conversion

| Field            | Description                                                                                                               | Type  |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
| `completions`    | Number of visits that viewed this page and completed a conversion                                                         | value |
| `conversionRate` | Percentage of visits that completed a conversion after viewing this page. Higher = greater conversion impact of this page | rate  |

> **Note:** Conversion queries must also pass conversion goal names via `conversionNames`.

**Block metrics (for `block_metrics`)**

If `metrics` is omitted, all are returned; if passed, only the specified ones. `blockName` and `screenshotUrl` are always returned.

| Field            | Description                                                                                                | Type  |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | ----- |
| `blockName`      | Block name                                                                                                 | text  |
| `screenshotUrl`  | Block screenshot URL                                                                                       | text  |
| `impression`     | PVs where users started seeing the current block                                                           | value |
| `impressionRate` | Share of PVs where users started seeing the current block                                                  | rate  |
| `dropoff`        | PVs that left the current block without clicking through or converting                                     | value |
| `dropoffRate`    | Share of PVs that left the current block without clicking through or converting                            | rate  |
| `avgDuration`    | Average dwell time on this block after users stop scrolling. Longer dwell typically means greater interest | time  |
| `completions`    | Visits that stayed on a content block for a specific time and completed a conversion                       | value |
| `conversionRate` | Share of visits with conversion among visits that stayed on a block for a specific time                    | rate  |

**Element metrics (for `element_metrics`)**

If `metrics` is omitted, all are returned; if passed, only the specified ones. `elementName` is always returned.

| Field            | Description                                                           | Type  |
| ---------------- | --------------------------------------------------------------------- | ----- |
| `elementName`    | Element name                                                          | text  |
| `impression`     | PVs where users started seeing the current element                    | value |
| `impressionRate` | Share of PVs where users started seeing the current element           | rate  |
| `click`          | Number of clicks on the current element                               | value |
| `clickRate`      | Clicks ÷ impressions. Higher click rate = more engaging element       | rate  |
| `completions`    | Visits that clicked an element and completed a conversion             | value |
| `conversionRate` | Share of visits with conversion among visits that clicked the element | rate  |

#### Device type rules

| queryType         | Supported deviceType            | Notes                               |
| ----------------- | ------------------------------- | ----------------------------------- |
| `page_metrics`    | `ALL`, `PC`, `MOBILE`, `TABLET` | `ALL` returns all-device aggregates |
| `page_insight`    | `ALL`, `PC`, `MOBILE`, `TABLET` | `ALL` returns all-device aggregates |
| `block_metrics`   | `PC`, `MOBILE`, `TABLET`        | **`ALL` not supported**             |
| `element_metrics` | `PC`, `MOBILE`, `TABLET`        | **`ALL` not supported**             |

#### Block & element prerequisites

Before querying `block_metrics` or `element_metrics`, you must scan the page in the Ptengine product:

1. Open the target page in Ptengine Heatmap
2. Enable block / element detection
3. Save the configuration

If a page is not configured, the API returns `4008` (block not configured) or `4016` (element not configured).

#### Request examples

**Example 1: page traffic overview**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["visits", "pv", "uv", "bounceRate", "timeOnPage"],
    "lang": "EN"
  }'
```

**Example 2: page insight grouped by device type**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_insight",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "bounceRate", "clickRate"],
    "funName": "terminalType",
    "lang": "EN"
  }'
```

**Example 3: mobile block analytics with Japan filter**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "block_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "MOBILE",
    "rangeType": "MERGE_URL",
    "filters": [
      { "name": "country", "op": "include", "value": ["Japan"] }
    ],
    "lang": "EN"
  }'
```

**Example 4: page metrics for a specific conversion goal**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "completions", "conversionRate"],
    "conversionNames": ["Purchase complete"],
    "lang": "EN"
  }'
```

**Example 5: PC element click analytics**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "element_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "EN"
  }'
```

#### Notes

* Time-type fields (e.g. page `timeOnPage`, block `avgDuration`) are returned as readable strings with units (e.g. `"5s"`, `"1m 30s"`).
* Rate-type values are decimals (e.g. `bounceRate: 0.45` means 45%).
* The API's data source matches the Ptengine product UI; results should match.
* If the requested URL has never been captured under the profile, the API returns `200` but all metric values are `0`. No error.

***

### 2.3 Event

Event analytics. Query events by dimension, metric, and segment (the `filters` field in your request).

#### Request parameters

| Param        | Required | Type                  | Description                                                                                                                                                                                                                                                                                                                                     |
| ------------ | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`  | yes      | string                | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9`                                                                                                                                                                            |
| `startDate`  | yes      | string                | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                                                        |
| `endDate`    | yes      | string                | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                                                          |
| `dimensions` | yes      | (string \| object)\[] | Group-by dimensions array; must include `"eventName"`. Up to 3 non-time dimensions + at most 1 time dimension (`day` / `hour` / `week` / `month`), matching the **Event > Segment** product page. Each item is a string (standard dimension name) or an object `{ name: "eventDimension", eventVariant: "<propName>" }` (custom event property) |
| `metrics`    | no       | string\[]             | Metric field names, defaults to `["eventCount"]`. Allowed: `eventCount`, `sessions`                                                                                                                                                                                                                                                             |
| `filters`    | no       | object\[]             | Segment (filter) conditions, see §2.1 [Filter](#filter)                                                                                                                                                                                                                                                                                         |

**Custom event properties**

If your events carry custom properties (e.g. the `purchase` event has a `price` property), you can group by or segment on those properties.

* **Group by property** — add to `dimensions`:

  ```json
  { "name": "eventDimension", "eventVariant": "price" }
  ```

  Results aggregate by `price` value.
* **Segment by property** — add to `filters`:

  ```json
  { "name": "eventDimension", "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100"] }
  ```

  Only sessions where `purchase` event has `price=100`.
* **Always lock the event when segmenting** — when segmenting by property, add an extra eventName filter, otherwise the query doesn't know which event to anchor on:

  ```json
  { "name": "eventName", "op": "include", "value": ["purchase"] }
  ```

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day", "country"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
      { "name": "eventName", "op": "include", "value": ["purchase"] },
      { "name": "country", "op": "include", "value": ["Japan", "China"] },
      { "name": "visitType", "op": "include", "value": ["New visits"] },
      { "name": "deviceType", "op": "include", "value": ["PC", "Mobile"] },
      {
        "name": "eventDimension",
        "eventName": "purchase",
        "eventVariant": "price",
        "op": "include",
        "value": ["100", "200"]
      }
    ]
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": [
            { "name": "eventName", "type": "dimension", "dataType": "STRING" },
            { "name": "day", "type": "dimension", "dataType": "DATE" },
            { "name": "country", "type": "dimension", "dataType": "STRING" },
            { "name": "eventCount", "type": "metric", "dataType": "INTEGER" },
            { "name": "sessions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "eventName": "purchase", "day": "2026-04-15", "country": "Japan", "eventCount": 320, "sessions": 250 }
        ]
    }
}
```

#### More examples

**a) Simplest — count by event name**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"]
  }'
```

**b) Time series — by day**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day"],
    "metrics": ["eventCount", "sessions"]
  }'
```

**c) Filter by conversion goal (fuzzy name match)**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "conversionName"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "conversionName", "op": "include", "value": ["ptmind"] }
    ]
  }'
```

> `conversionName` matches all goals whose names contain `"ptmind"`. If nothing matches, returns `4012`.

**d) Custom event property — group + filter**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", { "name": "eventDimension", "eventVariant": "position" }],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["gallery_item_impression"] },
        {
            "name": "eventDimension",
            "eventName": "gallery_item_impression",
            "eventVariant": "position",
            "op": "include",
            "value": ["home"]
        }
    ]
  }'
```

> Both filters are required and serve different purposes: the standalone `eventName` filter locks the query to `gallery_item_impression` (aggregation scope); the `eventDimension` filter further segments by `position == "home"`.

**e) Source distribution — UTM + source type**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "sourceType", "utmSource"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "sourceType", "op": "include", "value": ["Search", "Campaign"] }
    ]
  }'
```

**f) New visitors + PC + Japan/China**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "country"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "visitType", "op": "include", "value": ["New visits"] },
        { "name": "deviceType", "op": "include", "value": ["PC"] },
        { "name": "country", "op": "include", "value": ["Japan", "China"] }
    ]
  }'
```

**g) Exclude bounce sessions**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"],
    "metrics": ["eventCount", "sessions"],
    "filters": [{ "name": "exitType", "op": "exclude", "value": ["Bounce visits"] }]
  }'
```

#### Metadata

Returns all available metrics and dimensions (multi-language labels, optional `lang` switch).

**Request example:**

```bash
curl -X GET "https://xbackend.ptengine.com/open-api/v1/event/fields?lang=EN" \
  -H "x-api-key: pt-your-api-key"
```

**Response example (excerpt):**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": [
            { "field": "eventCount", "label": "Events", "description": "Number of times the event was triggered.", "dataType": "INTEGER" },
            { "field": "sessions", "label": "Sessions", "description": "Number of sessions in which the event was triggered.", "dataType": "INTEGER" }
        ],
        "dimensions": [
            { "field": "eventName", "label": "Event Name", "description": "Name of the event.", "dataType": "STRING", "category": "event" },
            { "field": "country", "label": "Country", "description": "Country.", "dataType": "STRING", "category": "geography" }
        ]
    }
}
```

#### Available metrics

| Field        | Description                                         | dataType |
| ------------ | --------------------------------------------------- | -------- |
| `eventCount` | Number of times the event was triggered             | INTEGER  |
| `sessions`   | Number of sessions in which the event was triggered | INTEGER  |

#### Available dimensions (for `dimensions[]` group-by)

| Field              | Description      |
| ------------------ | ---------------- |
| `eventName`        | Event Name       |
| `visitType`        | Visit type       |
| `exitType`         | Exit type        |
| `combinedPages`    | Entry page       |
| `conversionName`   | Conversion Name  |
| `day`              | Date             |
| `hour`             | Hour             |
| `week`             | Week             |
| `month`            | Month            |
| `sourceType`       | Source type      |
| `campaignUrl`      | Campaign URL     |
| `referralSource`   | Referral Website |
| `referralUrl`      | Referral URL     |
| `searchEngine`     | Search           |
| `socialNetwork`    | Social Media     |
| `socialUrl`        | Social URL       |
| `aiName`           | AI Search        |
| `utmCampaign`      | Campaign name    |
| `utmSource`        | Source           |
| `utmMedium`        | Medium           |
| `utmContent`       | Content          |
| `utmTerm`          | Term             |
| `deviceType`       | Device Type      |
| `deviceBrand`      | Brand            |
| `os`               | OS               |
| `osVersion`        | OS Version       |
| `browser`          | Browser          |
| `browserVersion`   | Browser Version  |
| `screenResolution` | Resolution       |
| `country`          | Country / Area   |
| `region`           | State / City     |

#### Notes

* `dimensions` is required and **must include the string `"eventName"`** — event queries must group by event name. You can include other dimensions and `eventDimension` objects alongside.
* **Dimension count limit:** up to 3 non-time dimensions + at most 1 time dimension (`day` / `hour` / `week` / `month`). Exceeding either limit returns `4018`.
* **When `eventName` filter is required:** if any of the following:

  * `dimensions` contains a non-`eventName`, non-time field (e.g. `country`, `sourceType`)
  * `dimensions` contains an `eventDimension` object
  * `filters` contains an `eventDimension` item

  Form: `{ "name": "eventName", "op": "include", "value": ["<event name>"] }`. Missing returns `4018`.

***

### 2.4 Data Center

Site-wide analytics — site metrics / traffic sources / geo distribution / device, OS, browser distribution / view details by dimension.

#### Request parameters

| Param            | Required | Type      | Description                                                                                                                                                                                                                                                                                                                                        |
| ---------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`      | yes      | string    | Query type: `overview` (summary data by topic), `dimension_table` (Top-N table grouped by a dimension), `metric_curve` (time series for a single metric)                                                                                                                                                                                           |
| `profileId`      | yes      | string    | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9`                                                                                                                                                                               |
| `startDate`      | yes      | string    | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                                                           |
| `endDate`        | yes      | string    | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                                                             |
| `filters`        | no       | object\[] | Filter conditions, see §2.1 [Filter](#filter)                                                                                                                                                                                                                                                                                                      |
| `conversionName` | no       | string    | Filter metrics by a single conversion goal. **When omitted, returns metrics aggregated across all conversions.** Applies only to `dimension_table` (any dimension except `combinedPages` / `originalPages` / `pageGroup`) and `metric_curve` (when `metric` ∈ `conversions` / `conversionRate` / `conversionValue`); other scenarios return `4018` |
| `lang`           | no       | string    | Language for labels: `EN` (default), `ZH`, `JP`. Only affects `overview` with `topic = "metrics"`, and the `label` / `description` on metric columns of `dimension_table`. Invalid values fall back to `EN`                                                                                                                                        |

#### Query types

**`overview` — Summary data by topic**

Returns overview data by topic.

**Required:** `topic`. Allowed values: `metrics` / `sources` / `location` / `device`.

> For finer details (specific search engine / referral URL / campaign name, or OS / browser distribution, etc.), use `queryType: "dimension_table"` with the corresponding `dimension`.

**`topic = "metrics"` — Metric overview**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "metrics",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "filters": [{ "name": "country", "op": "include", "value": ["Japan"] }],
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "topic": "metrics",
        "metrics": {
            "visits": {
                "value": "12,500",
                "label": "Visits",
                "description": "The number of times a site has been visited, a visitor may visit multiple times, browsing multiple pages at a time."
            },
            "users": {
                "value": "8,900",
                "label": "Unique visitors (UV)",
                "description": "The number of visitors who visited the site during the time. A visitor who comes to the site multiple times will count as 1 visitor."
            },
            "pageView": {
                "value": "32,000",
                "label": "Page views (PV)",
                "description": "The number of times the page has been viewed."
            },
            "newVisitsRate": {
                "value": "65.00%",
                "label": "% New visits",
                "description": "The percentage of visits that first time come to the site relative to the total number of visits."
            },
            "returnVisitsRate": {
                "value": "35.00%",
                "label": "% Returning visits",
                "description": "The percentage of visits that have visited the site before relative to the total number of visits."
            },
            "avgPageView": {
                "value": "2.56",
                "label": "PV / UV",
                "description": "The average pageviews a visitor viewed your pages. You can know how deep a visitor visits the site."
            },
            "avgVisits": {
                "value": "1.40",
                "label": "Visits / UV",
                "description": "The average times a visitor visits the site. You can know if most visitors will back to the site."
            },
            "avgVisitDuration": {
                "value": "3m 7s",
                "label": "Visit duration",
                "description": "The average duration of visits on the site. You can know if the site content attracts visitors to stay longer."
            },
            "avgLoadTime": {
                "value": "4s",
                "label": "Avg. page load time",
                "description": "The average time the page loaded. The longer the load time, the more likely to lose visitors."
            },
            "bounceRate": {
                "value": "42.00%",
                "label": "% Bounce",
                "description": "The percentage of visits that viewed only 1 page then left. You can know if the landing page attracts users to visit further pages."
            }
        }
    }
}
```

**`topic = "sources"` — Traffic sources**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "sources",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "topic": "sources",
        "totalVisits": 12500,
        "rows": [
            { "sourceType": "Direct", "visits": 5200 },
            { "sourceType": "Search", "visits": 3100 },
            { "sourceType": "Social", "visits": 1800 },
            { "sourceType": "Referral", "visits": 1500 },
            { "sourceType": "Campaign", "visits": 700 },
            { "sourceType": "AISearch", "visits": 200 }
        ]
    }
}
```

**`topic = "location"` — Geo distribution**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "location",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "topic": "location",
        "rows": [
            { "country": "Japan", "state": "Tokyo", "visits": 4200 },
            { "country": "Japan", "state": "Osaka", "visits": 1800 },
            { "country": "China", "state": "Shanghai", "visits": 1500 },
            { "country": "United States", "state": "California", "visits": 900 }
        ]
    }
}
```

**`topic = "device"` — Device distribution**

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "device",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "topic": "device",
        "rows": [
            {
                "deviceType": "PC",
                "visits": 7800,
                "osVersion": [
                    { "name": "Windows 10", "visits": 5200 },
                    { "name": "Windows 11", "visits": 1800 }
                ],
                "resolution": [
                    { "name": "1920x1080", "visits": 3200 },
                    { "name": "1366x768", "visits": 2100 }
                ],
                "browserVersion": [
                    { "name": "Chrome 120", "visits": 4500 },
                    { "name": "Safari 17", "visits": 800 }
                ]
            },
            {
                "deviceType": "Mobile",
                "visits": 3600,
                "osVersion": [
                    { "name": "iOS 17", "visits": 2100 },
                    { "name": "Android 14", "visits": 1500 }
                ],
                "brand": [
                    { "name": "Apple", "visits": 2100 },
                    { "name": "Samsung", "visits": 900 }
                ],
                "browserVersion": [
                    { "name": "Safari 17", "visits": 2100 },
                    { "name": "Chrome Mobile 120", "visits": 1300 }
                ]
            },
            {
                "deviceType": "Tablet",
                "visits": 1100,
                "osVersion": [{ "name": "iPadOS 17", "visits": 900 }],
                "brand": [{ "name": "Apple", "visits": 900 }],
                "browserVersion": [{ "name": "Safari 17", "visits": 900 }]
            }
        ]
    }
}
```

**`dimension_table` — Top-N table grouped by a dimension**

Returns a Top-N table grouped by a single dimension.

**Required:** `dimension` — see [Available dimensions](#dc-dimensions).

**Optional:** `sortBy` (string) / `sortOrder` (`asc`/`desc`) / `limit` (1-1000, default 1000). Response is capped at 1000 rows.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "country",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "sortBy": "visits",
    "sortOrder": "desc",
    "limit": 100,
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "country", "type": "dimension", "dataType": "STRING" },
            { "name": "visits", "type": "metric", "dataType": "INTEGER", "label": "Visits", "description": "The number of times a site has been visited, a visitor may visit multiple times, browsing multiple pages at a time." },
            { "name": "avgVisitDuration", "type": "metric", "dataType": "TIME", "label": "Visit duration", "description": "The average duration of visits on the site. You can know if the site content attracts visitors to stay longer." },
            { "name": "pageView", "type": "metric", "dataType": "INTEGER", "label": "Page views (PV)", "description": "The number of times the page has been viewed." },
            { "name": "newVisitsRate", "type": "metric", "dataType": "RATE", "label": "% New visits", "description": "The percentage of visits that first time come to the site relative to the total number of visits." },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "% Conversion", "description": "The percentage of visits that completed the specific conversion. Conversion rate = conversions / total visits. A higher conversion rate means this type of visit has better performance." },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "# Completions", "description": "The number of visits that completed the specific conversion." },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "% Bounce", "description": "The percentage of visits that viewed only 1 page then left. You can know if the landing page attracts users to visit further pages." }
        ],
        "rows": [
            {
                "country": "China",
                "visits": "619",
                "avgVisitDuration": "00:02:49",
                "pageView": "1,145",
                "newVisitsRate": "52.18%",
                "conversionRate": "96.28%",
                "conversions": "596",
                "bounceRate": "74.64%"
            },
            {
                "country": "Japan",
                "visits": "530",
                "avgVisitDuration": "00:00:08",
                "pageView": "553",
                "newVisitsRate": "99.81%",
                "conversionRate": "94.91%",
                "conversions": "503",
                "bounceRate": "96.04%"
            }
        ]
    }
}
```

> Each `metric` column carries `label` / `description` (language controlled by the `lang` field, defaults to `EN`). Metric values are formatted as strings to match the product UI columns: INTEGER with thousands separators (`"1,145"`), RATE as percentage (`"52.18%"`), `avgVisitDuration` as HH:MM:SS (`"00:02:49"`), `avgLoadTime` sub-second precision (`"2.45s"`). Parse the strings if you need the raw numeric values.

**Example: page list**

Top-N over "entry pages". Without `conversionName`, returns metrics aggregated across all conversions.

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "entryCombinedPages",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "sortBy": "entrances",
    "sortOrder": "desc",
    "limit": 50
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "Entrances", "description": "The number of visits that the page was visited as a landing page." },
            { "name": "newVisitsRate", "type": "metric", "dataType": "RATE", "label": "% New visits", "description": "The percentage of visits that first time come to the site relative to the total number of visits." },
            { "name": "avgPageVisits", "type": "metric", "dataType": "NUMBER", "label": "Avg. pageviews", "description": "The average number of pages visited after entering from this page." },
            { "name": "avgVisitDuration", "type": "metric", "dataType": "TIME", "label": "Visit duration", "description": "The average duration of visits on the site." },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "% Bounce", "description": "The percentage of visits that viewed only 1 page then left." },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "# Completions", "description": "The number of visits that completed the specific conversion." },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "% Conversion", "description": "The percentage of visits that completed the specific conversion." }
        ],
        "rows": [
            { "url": "https://ptengine.jp", "title": "Ptengineウェブ運営All-in-Oneプラットフォーム | ウェブの改善や改善業務はこれひとつで完結", "entrances": "253", "newVisitsRate": "71.15%", "avgPageVisits": "1.29", "avgVisitDuration": "00:01:55", "bounceRate": "84.58%", "conversions": "253", "conversionRate": "100.00%" },
            { "url": "https://ptengine.jp/app/login", "title": "ログイン | Ptengine", "entrances": "186", "newVisitsRate": "31.18%", "avgPageVisits": "1.62", "avgVisitDuration": "00:01:24", "bounceRate": "44.62%", "conversions": "172", "conversionRate": "92.47%" }
        ]
    }
}
```

> Page-URL dimensions (`combinedPages` / `originalPages` / `entryCombinedPages` / `entryOriginalPages`) always return the columns `url` + `title`; the `pageGroup` dimension returns the group name as a string.
>
> **About `conversionName`**:
>
> * `entryCombinedPages` / `entryOriginalPages` (entry pages) **support** it: when supplied, the `conversions` and `conversionRate` columns are scoped to the selected goal (matching the "Select conversion" dropdown above the entry-page table in the product UI). Other metrics are unchanged.
> * `combinedPages` / `originalPages` / `pageGroup` (pages / page groups) **do not** support it: these dimensions do not compute conversion metrics, so passing `conversionName` returns `4018`.

**Example: filter metrics by a single conversion goal**

When `conversionName` is set, metrics (`conversions` / `conversionRate` etc.) are computed against the matched conversion only.

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "entryCombinedPages",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "conversionName": "ptmind",
    "sortBy": "conversions",
    "sortOrder": "desc",
    "limit": 20
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "Entrances", "description": "The number of visits that the page was visited as a landing page." },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "# Completions", "description": "The number of visits that completed the specific conversion." },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "% Conversion", "description": "..." }
        ],
        "rows": [
            { "url": "https://ptengine.jp/app/signup", "title": "登録 | Ptengine", "entrances": "1,042", "conversions": "312", "conversionRate": "29.94%" },
            { "url": "https://ptengine.jp", "title": "Ptengineウェブ運営All-in-Oneプラットフォーム | ウェブの改善や改善業務はこれひとつで完結", "entrances": "815", "conversions": "187", "conversionRate": "22.94%" }
        ]
    }
}
```

**`metric_curve` — Time series for a single metric**

Returns a time series for a single metric.

**Required:** `metric`. Allowed values: see [Available metrics](#dc-metrics); `granularity`. Allowed values: `hour` / `day` / `week` / `month`. Response `time` field format: `YYYY-MM-DD` (or `YYYY-MM-DDTHH` for `hour` granularity).

> **`hour` granularity constraint**: `startDate` and `endDate` must be the same day; otherwise `4002` is returned. `day` / `week` / `month` have no such constraint.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metric_curve",
    "metric": "visits",
    "granularity": "day",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "filters": [{ "name": "deviceType", "op": "include", "value": ["PC"] }]
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "metric": "visits",
        "granularity": "day",
        "points": [
            { "time": "2026-04-01", "value": "420" },
            { "time": "2026-04-02", "value": "510" }
        ]
    }
}
```

#### Available metrics

| Metric             | Type    | Description          |
| ------------------ | ------- | -------------------- |
| `visits`           | INTEGER | Visits               |
| `users`            | INTEGER | Unique visitors (UV) |
| `pageView`         | INTEGER | Page views (PV)      |
| `newVisitsRate`    | RATE    | % New visits         |
| `returnVisitsRate` | RATE    | % Returning visits   |
| `avgVisits`        | RATE    | Visits / UV          |
| `avgPageView`      | RATE    | PV / UV              |
| `avgVisitDuration` | TIME    | Visit duration       |
| `bounceRate`       | RATE    | % Bounce             |
| `avgLoadTime`      | TIME    | Avg. page load time  |
| `conversions`      | INTEGER | # Completions        |
| `conversionRate`   | RATE    | % Conversion         |
| `conversionValue`  | NUMBER  | Conversion value     |

#### Available dimensions (for `queryType: "dimension_table"`)

| Dimension            | Description          |
| -------------------- | -------------------- |
| `country`            | Country / Area       |
| `state`              | State / City         |
| `os`                 | OS                   |
| `osVersion`          | OS Version           |
| `browser`            | Browser              |
| `browserVersion`     | Browser Version      |
| `resolution`         | Resolution           |
| `brand`              | Brand                |
| `sourceType`         | Source Type          |
| `campaign`           | Campaign             |
| `campaignUrl`        | Campaign URL         |
| `referral`           | Referral             |
| `referralUrl`        | Referral URL         |
| `search`             | Search engine        |
| `socialMedia`        | Social media         |
| `socialUrl`          | Social URL           |
| `aiName`             | AI search source     |
| `adSource`           | UTM source           |
| `adName`             | UTM campaign         |
| `adMedium`           | UTM medium           |
| `adTerm`             | UTM term             |
| `adContent`          | UTM content          |
| `combinedPages`      | Combined pages       |
| `originalPages`      | Original pages       |
| `pageGroup`          | Page group           |
| `entryCombinedPages` | Entry combined pages |
| `entryOriginalPages` | Entry original pages |

***

### 2.5 Conversion

Conversion goal analytics — completions, value, source distribution, funnel.

#### Request parameters

| Param            | Required    | Type      | Description                                                                                                                                                                                                                                                                                                   |
| ---------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`      | yes         | string    | Query type: `metrics` (conversion metrics), `metric_curve` (time trend), `sources_breakdown` (distribution by source), `ad_name_breakdown` (distribution by ad name), `ad_source_breakdown` (distribution by ad source), `funnel` (funnel), `regular` (positive goals list), `negative` (negative goals list) |
| `profileId`      | yes         | string    | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9`                                                                                                                                          |
| `startDate`      | yes         | string    | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                      |
| `endDate`        | yes         | string    | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                                                                                                                                                                        |
| `conversionName` | conditional | string    | Goal name (must hit exactly 1 goal, otherwise 4012). **Only required for `funnel`**; other queryTypes do NOT need `conversionName` (it will be ignored even if passed)                                                                                                                                        |
| `metric`         | conditional | string    | Required for `metric_curve` — `completions` / `conversionRate` / `conversionValue`                                                                                                                                                                                                                            |
| `granularity`    | conditional | string    | Required for `metric_curve` — `hour` / `day` / `week` / `month`                                                                                                                                                                                                                                               |
| `filters`        | no          | object\[] | Filter (segment) conditions, see §2.1 [Filter](#filter)                                                                                                                                                                                                                                                       |
| `lang`           | no          | string    | Language for label/description: `EN` (default), `ZH`, `JP`. Currently only applied to `queryType = "metrics"` response. Invalid values fall back to `EN`                                                                                                                                                      |

#### Query types

**`metrics` — Conversion metrics**

Returns 5 metrics: **Completions / Conversion rate / Conversion value / Revenue / Loss**. Each metric is wrapped as `{ value, label }`; `label` honors the `lang` field.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metrics",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "lang": "EN",
    "filters": [{ "name": "country", "op": "include", "value": ["Japan"] }]
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "metrics",
        "metrics": {
            "conversions":     { "value": "214",     "label": "Completions" },
            "conversionRate":  { "value": "45.73%",  "label": "Conversion rate" },
            "conversionValue": { "value": "-21,100", "label": "Conversion value" },
            "revenue":         { "value": "0",       "label": "Revenue" },
            "loss":            { "value": "-21,100", "label": "Loss" }
        }
    }
}
```

**Field meanings:**

| Field             | Calculation                                                                 |
| ----------------- | --------------------------------------------------------------------------- |
| `conversions`     | Visits that completed any positive conversion (aggregated across all goals) |
| `conversionRate`  | `conversions / total visits`                                                |
| `conversionValue` | `revenue + loss` (may be negative)                                          |
| `revenue`         | Total revenue from positive conversion goals (cvValue ≥ 0)                  |
| `loss`            | Total loss from negative conversion goals (cvValue < 0), negative           |

**`metric_curve` — Time trend**

Returns the time series of a single conversion metric.

**Required:** `metric` — `completions` / `conversionRate` / `conversionValue`; `granularity` — `hour` / `day` / `week` / `month`.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metric_curve",
    "metric": "completions",
    "granularity": "day",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "metric_curve",
        "metric": "completions",
        "granularity": "day",
        "points": [
            { "time": "2026-04-01", "value": "24" },
            { "time": "2026-04-02", "value": "35" }
        ]
    }
}
```

**`sources_breakdown` — Distribution by source**

Breakdown of conversions by traffic source.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "sources_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "sources_breakdown",
        "columns": [
            { "name": "sourceType", "type": "dimension", "dataType": "STRING" },
            { "name": "sourceName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "sourceType": "Direct", "sourceName": "no refer", "conversions": 1259 },
            { "sourceType": "Search", "sourceName": "google", "conversions": 13 },
            { "sourceType": "Referral", "sourceName": "https://example.com/", "conversions": 12 }
        ]
    }
}
```

**`ad_name_breakdown` — Distribution by ad name**

Breakdown of conversions by ad name (UTM Campaign).

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "ad_name_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "ad_name_breakdown",
        "columns": [
            { "name": "adName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "adName": "spring_sale_2026", "conversions": 320 },
            { "adName": "brand_awareness_q1", "conversions": 158 },
            { "adName": "retargeting_jp", "conversions": 92 }
        ]
    }
}
```

**`ad_source_breakdown` — Distribution by ad source**

Breakdown of conversions by ad source (UTM Source).

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "ad_source_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "ad_source_breakdown",
        "columns": [
            { "name": "adSource", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "adSource": "google", "conversions": 420 },
            { "adSource": "facebook", "conversions": 180 },
            { "adSource": "newsletter", "conversions": 65 }
        ]
    }
}
```

**`funnel` — Funnel**

Returns per-step entries, dropoff, and conversion-to-next rate.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "funnel",
    "conversionName": "ptmind signup",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "funnel",
        "conversionName": "ptmind signup",
        "conversionId": "1753350579776",
        "summary": {
            "totalConversions": 700,
            "totalConversionRate": "70.00%"
        },
        "steps": [
            {
                "stepId": 1, "entries": 1000, "external": 1000, "dropoff": 200,
                "conversionToNextRate": "80.00%",
                "entryPaths":   [{ "url": "https://example.com/landing", "visits": 600 }],
                "dropoffPaths": [{ "url": "Exit", "visits": 5 }, { "url": "https://example.com/other", "visits": 195 }]
            },
            {
                "stepId": 2, "entries": 800, "external": 0, "dropoff": 100,
                "conversionToNextRate": "87.50%",
                "entryPaths": [],
                "dropoffPaths": [{ "url": "https://example.com/other", "visits": 100 }]
            },
            {
                "stepId": 3, "entries": 700, "external": 0, "dropoff": 0,
                "conversionToNextRate": null,
                "entryPaths": [], "dropoffPaths": []
            }
        ]
    }
}
```

**Field meanings:**

| Field                         | Meaning                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `entries`                     | Entries to this step (`external + convert`)                                    |
| `external`                    | Visits that entered this step directly (not from the previous step)            |
| `dropoff`                     | Dropoff at this step = `entries − next step convert` (0 on the last step)      |
| `conversionToNextRate`        | Conversion rate to the next step (`null` on the last step)                     |
| `entryPaths`                  | URLs of external entry pages for this step, sorted by visits desc              |
| `dropoffPaths`                | URLs of dropoff pages for this step, sorted by visits desc; untracked → `Exit` |
| `summary.totalConversions`    | Final conversions (entries of the last step)                                   |
| `summary.totalConversionRate` | Last-step `entries` / sum of `external` across all steps                       |

**`regular` — Positive goals list**

Returns all "positive" (value ≥ 0) conversion goals with their metrics, one row per goal.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "regular",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "data": {
        "queryType": "regular",
        "columns": [
            { "name": "conversionName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE" },
            { "name": "revenue", "type": "metric", "dataType": "NUMBER" }
        ],
        "rows": [
            { "conversionName": "ptmind signup", "conversions": "850", "conversionRate": "6.20%", "revenue": "0" },
            { "conversionName": "Download whitepaper", "conversions": "130", "conversionRate": "1.00%", "revenue": "0" }
        ]
    }
}
```

**`negative` — Negative goals list**

Same shape as `regular`. Returns all "negative" (value < 0, i.e. loss goals) conversion goals, with an extra `loss` column per row (absolute loss value).

#### Notes

* `conversionName` is only required for `funnel`; other queryTypes do NOT need `conversionName` (it will be ignored if passed).
* For `funnel`, `conversionName` must hit **exactly one** goal. If multiple match (e.g. `"ptmind"` matches both `"ptmind signup"` and `"ptmind purchase"`), it returns 4012 with the list of matches — use a more specific name.
* Use `POST /v1/conversion/goals` to list all goals before constructing your request.

***

## 3. Experience

### 3.1 List experiences

Returns basic info for all experiences in the profile, including goals and version lists. The `id`, `goalId`, and `versionId` used by subsequent endpoints all come from this response.

#### Request parameters

| Param       | Required | Type   | Description                                                                                                                                                          |
| ----------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | yes      | string | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/list \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
            "name": "Spring Promo Popup",
            "status": "RUNNING",
            "type": "POPUP",
            "goals": [{ "id": "6a8bedde-...", "name": "Purchase complete" }],
            "versions": [
                { "id": "a2696719-...", "name": "Control" },
                { "id": "b3c8f210-...", "name": "Pattern 1" }
            ]
        }
    ]
}
```

| Field      | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| `id`       | Experience ID, used as `id` param in report endpoints             |
| `name`     | Experience name                                                   |
| `status`   | Status: `DRAFT` / `RUNNING` / `PAUSE` / `SCHEDULED`               |
| `type`     | Type: `POPUP` / `STICKY_BAR` / `INLINE` / `ADVANCED` / `REDIRECT` |
| `goals`    | Goal list, used as `goalId` in A/B test endpoints                 |
| `versions` | Version list, used as `versionId` in form endpoint                |

***

### 3.2 List user properties

Returns the list of available user properties. When the insight endpoint uses `dimension: "userProperty"`, fetch `property` from this endpoint.

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/user-properties \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        { "name": "plan_name", "displayName": "Plan Name", "source": ["code"], "type": "STRING" },
        { "name": "signup_date", "displayName": "Signup Date", "source": ["default"], "type": "DATE" }
    ]
}
```

***

### 3.3 Experience overview metrics

Batch query metrics for multiple experiences.

#### Request parameters

| Param         | Required | Type      | Description                                                                                                                                                          |
| ------------- | -------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`   | yes      | string    | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `experiences` | yes      | object\[] | Experience list (`id` + `name`, from the list endpoint)                                                                                                              |
| `metrics`     | no       | string\[] | Metric fields to return. If omitted, returns all defaults. Supported fields below                                                                                    |
| `lang`        | no       | string    | Response language: `EN` (default), `ZH`, `JP`                                                                                                                        |

**Supported `metrics` fields:**

| Field                | Description                                                    | Type    |
| -------------------- | -------------------------------------------------------------- | ------- |
| `viewedUsers`        | Number of users who viewed the experience                      | value   |
| `views`              | Number of times the experience was viewed                      | value   |
| `clickedUsers`       | Number of users who clicked a button or link in the experience | value   |
| `clickRate`          | Click ratio of users in the experience                         | rate    |
| `closedUsers`        | Number of users who closed the popup / sticky bar              | value   |
| `closeRate`          | Close ratio of users for popup / sticky bar                    | rate    |
| `formSubmittedUsers` | Number of users who submitted the form                         | value   |
| `formSubmitRate`     | Form submit ratio                                              | rate    |
| `goalReachedUsers`   | Users who reached a goal after viewing the experience          | value   |
| `goalReachRate`      | Goal-reach ratio of users who viewed the experience            | rate    |
| `goalStatus`         | Goal status by user share, property sum, or average            | value   |
| `avgVisitDuration`   | Average visit duration of users who viewed the experience      | time    |
| `avgPagesPerVisit`   | Average pages per visit                                        | decimal |
| `bounceRate`         | Bounce rate                                                    | rate    |
| `lastUpdatedTime`    | Last updated time                                              | text    |
| `lastUpdatedMember`  | Last updater                                                   | text    |
| `createdTime`        | Created time                                                   | text    |
| `createdMember`      | Creator                                                        | text    |
| `runningPeriod`      | Running period                                                 | text    |
| `tags`               | Custom property tags                                           | text    |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/overview \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "experiences": [
      { "id": "6c3bad4b-...", "name": "Spring Promo Popup" },
      { "id": "5bb77b97-...", "name": "Signup Guide" }
    ],
    "metrics": ["viewedUsers", "clickRate", "bounceRate"],
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "name": "Spring Promo Popup",
            "viewedUsers": { "value": 100, "label": "Viewed Users", "description": "Number of users who viewed the experience." },
            "clickRate": { "value": "5.00%", "label": "Click Rate", "description": "Click ratio of users in the experience." },
            "bounceRate": { "value": "42.86%", "label": "Bounce Rate", "description": "Bounce rate of visits that viewed the experience." }
        }
    ]
}
```

**All metrics return `{ value, label, description }`**. `label` and `description` follow `lang`.

***

### 3.4 Key metrics

Query overall metrics for a single experience.

#### Request parameters

| Param       | Required | Type   | Description                                                                                                                                                          |
| ----------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | yes      | string | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `id`        | yes      | string | Experience ID (from the list endpoint)                                                                                                                               |
| `startDate` | yes      | string | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                             |
| `endDate`   | yes      | string | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                               |
| `lang`      | no       | string | Language for label/description: `EN` (default), `ZH`, `JP`                                                                                                           |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/metrics \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Promo Popup",
        "items": [
            {
                "viewedUsers": { "value": 100, "label": "Viewed Users", "description": "..." },
                "views": { "value": 300, "label": "Views", "description": "..." },
                "clickedUsers": { "value": 50, "label": "Clicked Users", "description": "..." },
                "clickRate": { "value": "41.67%", "label": "Click Rate", "description": "..." },
                "goals": [
                    {
                        "name": "Purchase complete",
                        "reachedUsers": { "value": 5, "label": "Reached Users", "description": "..." },
                        "reachRate": { "value": "5.00%", "label": "Reach Rate", "description": "..." },
                        "value": { "value": null, "label": "Goal Status", "description": "..." }
                    }
                ],
                "avgVisitDuration": { "value": "06:33", "label": "Avg. Visit Duration", "description": "..." },
                "avgPagesPerVisit": { "value": "2.50", "label": "Avg. Pages per Visit", "description": "..." },
                "bounceRate": { "value": "42.86%", "label": "Bounce Rate", "description": "..." }
            }
        ]
    }
}
```

> **Note:** Returned metrics are filtered by experience type. For example, INLINE types don't return `clickedUsers` / `closedUsers`; experiences without forms don't return `formSubmittedUsers`.

***

### 3.5 Segment details

Query single-experience metrics grouped by dimension.

#### Request parameters

| Param          | Required    | Type   | Description                                                                                                                                                          |
| -------------- | ----------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | yes         | string | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `id`           | yes         | string | Experience ID (from the list endpoint)                                                                                                                               |
| `startDate`    | yes         | string | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                             |
| `endDate`      | yes         | string | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                               |
| `dimension`    | yes         | string | Primary dimension, see table below                                                                                                                                   |
| `subDimension` | no          | string | Secondary dimension                                                                                                                                                  |
| `property`     | conditional | object | Required when `dimension="userProperty"`. From the user-properties endpoint                                                                                          |
| `lang`         | no          | string | Language for label/description: `EN` (default), `ZH`, `JP`                                                                                                           |

**Allowed `dimension` values:**

| dimension      | Description      | Supports subDimension           |
| -------------- | ---------------- | ------------------------------- |
| `visitPage`    | Page             | ❌                               |
| `terminalType` | Device type      | ✅                               |
| `sourceType`   | Source type      | ✅                               |
| `utmCampaign`  | Campaign name    | ✅                               |
| `utmSource`    | Campaign source  | ✅                               |
| `utmMedium`    | Campaign medium  | ✅                               |
| `utmTerm`      | Campaign term    | ✅                               |
| `utmContent`   | Campaign content | ✅                               |
| `sourceUrl`    | Source URL       | ✅                               |
| `sourceHost`   | Source host      | ✅                               |
| `aiName`       | AI name          | ✅                               |
| `visitType`    | New / Returning  | ✅                               |
| `country`      | Country / Area   | ✅ (cannot combine with region)  |
| `region`       | Region           | ✅ (cannot combine with country) |
| `userProperty` | User property    | ❌ (requires `property`)         |

**userProperty example:** When `dimension` is `userProperty`, you must also pass `property`:

```json
{ "property": { "name": "plan_name", "source": ["code"], "type": "STRING" } }
```

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/insight \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "dimension": "terminalType",
    "subDimension": "visitType",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Promo Popup",
        "items": [
            {
                "name": "PC",
                "subName": "New visits",
                "viewedUsers": { "value": 80, "label": "Viewed Users", "description": "..." },
                "bounceRate": { "value": "38.00%", "label": "Bounce Rate", "description": "..." }
            },
            {
                "name": "Mobile",
                "subName": "Returning visits",
                "viewedUsers": { "value": 20, "label": "Viewed Users", "description": "..." },
                "bounceRate": { "value": "55.00%", "label": "Bounce Rate", "description": "..." }
            }
        ]
    }
}
```

***

### 3.6 A/B test results

A/B test results comparing each version, including uplift and probability-to-win.

#### Request parameters

| Param                 | Required    | Type    | Description                                                                                                                                                          |
| --------------------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | yes         | string  | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `id`                  | yes         | string  | Experience ID (from the list endpoint)                                                                                                                               |
| `startDate`           | yes         | string  | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                             |
| `endDate`             | yes         | string  | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                               |
| `compareBy`           | yes         | string  | Comparison baseline metric, see below                                                                                                                                |
| `goalId`              | conditional | string  | Required when `compareBy="goalReached"` (from list endpoint goals)                                                                                                   |
| `showDeletedVersions` | no          | boolean | Include deleted versions, default false                                                                                                                              |
| `lang`                | no          | string  | Language for label/description: `EN` (default), `ZH`, `JP`                                                                                                           |

**Allowed `compareBy` values:**

| compareBy            | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `viewedUsers`        | Users who viewed the experience                      |
| `clickedUsers`       | Users who clicked a button or link in the experience |
| `closedUsers`        | Users who closed the popup / sticky bar              |
| `formSubmittedUsers` | Users who submitted the form                         |
| `goalReached`        | Goal reached (requires `goalId`)                     |
| `avgVisitDuration`   | Average visit duration                               |
| `avgPagesPerVisit`   | Average pages per visit                              |
| `bounceRate`         | Bounce rate                                          |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/abtest/metrics \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-084d-4828-b874-43568cd2f27f",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Promo Popup",
        "items": [
            {
                "name": "Control",
                "viewedUsers": { "value": 50, "label": "Viewed Users", "description": "..." },
                "goalReachedUsers": { "value": 5, "label": "Reached Users", "description": "..." },
                "goalReachRate": { "value": "10.00%", "label": "Reach Rate", "description": "..." },
                "uplift": { "value": "Baseline", "label": "Uplift", "description": "..." },
                "probabilityToBeBest": { "value": null, "label": "Probability to Win", "description": "..." }
            },
            {
                "name": "Pattern 1",
                "viewedUsers": { "value": 50, "label": "Viewed Users", "description": "..." },
                "goalReachedUsers": { "value": 8, "label": "Reached Users", "description": "..." },
                "goalReachRate": { "value": "16.00%", "label": "Reach Rate", "description": "..." },
                "uplift": { "value": "+60.00%", "label": "Uplift", "description": "..." },
                "probabilityToBeBest": { "value": "85.30%", "label": "Probability to Win", "description": "..." }
            }
        ]
    }
}
```

> * Response only contains the metric corresponding to `compareBy`, plus `uplift` + `probabilityToBeBest`.
> * Baseline `uplift` is `"Baseline"`. Other versions get a percentage (e.g. `"+50.00%"` or `"-10.00%"`).

***

### 3.7 A/B test results — segment details

A/B test version comparison grouped by dimension.

#### Request parameters

| Param                 | Required    | Type    | Description                                                                                                                                                          |
| --------------------- | ----------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | yes         | string  | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `id`                  | yes         | string  | Experience ID (from the list endpoint)                                                                                                                               |
| `startDate`           | yes         | string  | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                             |
| `endDate`             | yes         | string  | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                               |
| `compareBy`           | yes         | string  | Comparison metric (same as 3.6)                                                                                                                                      |
| `goalId`              | conditional | string  | Required when `compareBy="goalReached"`                                                                                                                              |
| `dimension`           | yes         | string  | Primary dimension (same as 3.5)                                                                                                                                      |
| `subDimension`        | no          | string  | Secondary dimension                                                                                                                                                  |
| `property`            | conditional | object  | Required when `dimension="userProperty"`                                                                                                                             |
| `showDeletedVersions` | no          | boolean | Include deleted versions, default false                                                                                                                              |
| `lang`                | no          | string  | Language for label/description: `EN` (default), `ZH`, `JP`                                                                                                           |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/abtest/insight \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-...",
    "dimension": "terminalType",
    "lang": "EN"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Promo Popup",
        "items": [
            {
                "name": "PC",
                "versions": [
                    {
                        "name": "All versions",
                        "viewedUsers": { "value": 40, "label": "Viewed Users", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "Uplift", "description": "..." }
                    },
                    {
                        "name": "Control",
                        "viewedUsers": { "value": 20, "label": "Viewed Users", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "Uplift", "description": "..." }
                    },
                    {
                        "name": "Pattern 1",
                        "viewedUsers": { "value": 20, "label": "Viewed Users", "description": "..." },
                        "uplift": { "value": "+30.00%", "label": "Uplift", "description": "..." }
                    }
                ]
            }
        ]
    }
}
```

***

### 3.8 Form submissions

Detailed form submission data for a specific version.

#### Request parameters

| Param       | Required | Type   | Description                                                                                                                                                          |
| ----------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | yes      | string | Site ID (8 chars). Must match the profile bound to the API Key. Find it in the Ptengine URL, e.g. `https://www.ptengine.jp/app/{profileId}/home` contains `566d12f9` |
| `id`        | yes      | string | Experience ID (from the list endpoint)                                                                                                                               |
| `versionId` | yes      | string | Version ID (from `versions` in the list endpoint)                                                                                                                    |
| `startDate` | yes      | string | Start date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                             |
| `endDate`   | yes      | string | End date: `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                                               |

**Request example:**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/form \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "versionId": "a2696719-6375-456b-8dbc-7e3d273beb6d",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'
```

**Response example:**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": ["submittedAt", "Email", "Picture choice", "choice-test2"],
        "rows": [
            {
                "submittedAt": "2026/04/09 19:14:33",
                "Email": "test@example.com",
                "Picture choice": "Option 3",
                "choice-test2": ""
            },
            {
                "submittedAt": "2026/04/08 17:40:05",
                "Email": "user@example.com",
                "Picture choice": "",
                "choice-test2": "Option 1,Option 2"
            }
        ]
    }
}
```

> * `columns` is dynamic, generated from the actual form fields.
> * Each row in `rows` is a single submission. Empty fields are returned as empty strings.

***

### 3.9 Available metrics

#### Basic metrics (all types)

| Field              | Format                        | Description          |
| ------------------ | ----------------------------- | -------------------- |
| `viewedUsers`      | number                        | Viewed users         |
| `views`            | number                        | Views                |
| `avgVisitDuration` | duration (`MM:SS`/`HH:MM:SS`) | Avg. visit duration  |
| `avgPagesPerVisit` | decimal (`"2.50"`)            | Avg. pages per visit |
| `bounceRate`       | percentage (`"42.86%"`)       | Bounce rate          |

#### Popup-class metrics (only POPUP / STICKY\_BAR / REDIRECT / ADVANCED with popup)

| Field          | Format     | Description   |
| -------------- | ---------- | ------------- |
| `clickedUsers` | number     | Clicked users |
| `clickRate`    | percentage | Click rate    |
| `closedUsers`  | number     | Closed users  |
| `closeRate`    | percentage | Close rate    |

#### Form-class metrics (only for experiences with forms configured)

| Field                | Format     | Description          |
| -------------------- | ---------- | -------------------- |
| `formSubmittedUsers` | number     | Form submitted users |
| `formSubmitRate`     | percentage | Form submit rate     |

#### Goal data

| Field                  | Description                                  |
| ---------------------- | -------------------------------------------- |
| `goals[].name`         | Goal name                                    |
| `goals[].reachedUsers` | Reached users                                |
| `goals[].reachRate`    | Reach rate                                   |
| `goals[].value`        | Reached value (null = counted by user share) |

***

## Appendix

### A. Error codes

| Code   | HTTP status | Description                                                                                                                                                            |
| ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `4010` | 401         | Missing `x-api-key` header                                                                                                                                             |
| `4011` | 401         | Invalid API Key                                                                                                                                                        |
| `4030` | 403         | `profileId` does not match the profile bound to the API Key                                                                                                            |
| `4031` | 403         | API Key lacks query permission (scope `query` required)                                                                                                                |
| `4001` | 400         | Invalid `queryType`                                                                                                                                                    |
| `4002` | 400         | Invalid date format; must be `YYYY-MM-DD` or `YYYY/MM/DD`                                                                                                              |
| `4003` | 400         | Query date exceeds the plan's data retention period                                                                                                                    |
| `4006` | 400         | `page_insight` type requires `funName`                                                                                                                                 |
| `4007` | 400         | `block_metrics` requires specific deviceType (PC/MOBILE/TABLET); ALL not supported                                                                                     |
| `4008` | 400         | Page block not configured. Please scan the page in the product first                                                                                                   |
| `4009` | 400         | `element_metrics` requires specific deviceType (PC/MOBILE/TABLET); ALL not supported                                                                                   |
| `4012` | 400         | No matching conversion goal                                                                                                                                            |
| `4013` | 400         | Missing required field (the response message names the specific field)                                                                                                 |
| `4014` | 400         | Invalid `deviceType`; must be `ALL`, `PC`, `MOBILE`, or `TABLET`                                                                                                       |
| `4015` | 400         | Invalid `dimension` / `subDimension` (response message gives details)                                                                                                  |
| `4016` | 400         | Page element not configured. Please scan the page in the product first                                                                                                 |
| `4017` | 400         | Invalid `compareBy` (response message lists allowed values)                                                                                                            |
| `4018` | 400         | Invalid field (`/event/query` / `/insight/query` / `/conversion/query`: dimension / metric / queryType / topic / granularity not allowed, or dimension count exceeded) |
| `4019` | 400         | Invalid filter operator or value (must be `include`/`exclude`; `value` must be a non-empty array; sortOrder/limit out of range)                                        |
| `4040` | 404         | Experience not found (`id` does not exist under this profile)                                                                                                          |
| `4290` | 429         | Rate limit exceeded (per minute)                                                                                                                                       |
| `4291` | 429         | Rate limit exceeded (per day)                                                                                                                                          |
| `5000` | 500         | Internal server error                                                                                                                                                  |

The `message` is returned in the language requested by `lang` (body or query: EN/ZH/JP). If not specified or invalid, falls back to English.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://helps.ptengine.com/en/developer/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.