Open API Documentation

---

1. General

1.1 Overview

Ptengine Open API provides RESTful endpoints for querying heatmap analytics data programmatically. You can integrate this API with AI Agents to automatically construct queries using natural language.

Base URL:

https://xbackend.ptengine.com/

---

1.2 Authentication

All API requests require an API Key passed via the x-api-key header.

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

How to obtain an API Key:

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

1. Log in to the Ptengine product

2. Navigate to the Experience module

3. Click the settings icon (⚙) in the top right corner, select "External App Integration"

4. Switch to the "API Keys" tab

5. Click "Create API Key", enter a name and select permissions (Data Upload / Data Query)

6. Copy and securely store your key (it will only be shown once)

---

1.3 Rate Limits

Rate 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 information is returned in 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

---

2. Heatmap Data Query

2.1 Query Heatmap Data

POST /open-api/v1/heatmap/query

The unified query endpoint. Use the queryType parameter to select the type of data you want.

Request Body

{
    "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", "clickRate"],
    "conversionNames": [],
    "filters": [],
    "lang": "EN"
}

Request Parameters

Parameter	Required	Type	Description
queryType	Yes	string	Query type. One of: page_metrics, page_insight, block_metrics, element_metrics
profileId	Yes	string	Site ID (8-character string). Must match the profile associated with your API key. You can find it in your Ptengine URL: https://www.ptengine.jp/app/{profileId}/home, e.g. 566d12f9
url	Yes	string	The page URL to query data for.
startDate	Yes	string	Start date in YYYY-MM-DD or YYYY/MM/DD format.
endDate	Yes	string	End date in YYYY-MM-DD or YYYY/MM/DD format.
deviceType	Yes	string	Device type filter. See section 5.1 for details.
rangeType	No	string	URL matching mode. MERGE_URL (default): aggregates data across URL parameter variants. URL: exact URL match.
metrics	No	string[]	If not provided, all metrics are returned. If provided, only specified metrics are returned. See section 6 for available metrics.
conversionNames	No	string[]	Conversion goal names for fuzzy matching. Example: ["購入完了", "会員登録"]
filters	No	object[]	Filter conditions. Each item has name (filter type), op (include/exclude), value (array of values). See filter types table below.
lang	No	string	Language for labels: EN (default), ZH, JP. Invalid values fall back to EN
funName	Conditional	string	Required for page_insight only. Options: terminalType (device type), sourceType (traffic source), visitType (new/return visit), aiName (AI Name), utmCampaign (UTM Campaign), utmSource (UTM Source), utmMedium (UTM Medium), utmTerm (UTM Term), utmContent (UTM Content), week, day

Filter Conditions (filters)

Each filter item format: { "name": "filterType", "op": "include or exclude", "value": ["value1", "value2"] }

Supported filter types:

Fixed values (no need to call filter-values API):

name	Description	Available 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 values (query via filter-values API):

name	Description	value examples
os	OS	["Windows", "Mac OS X"]
osVersion	OS Version	["Windows 10", "Mac OS X 10.15.7", "iOS 17.0"]
browser	Browser	["Chrome", "Mobile Safari", "Edge"]
browserVersion	Browser Version	["Chrome 124.0.0", "Edge 146.0.0", "Mobile Safari 13.0.3"]
screenResolution	Resolution	["1920x1080", "1440x900"]
deviceBrand	Brand	["Apple", "Samsung"]
country	Country / Area	["Japan", "China", "United States"]
region	State / City	["Tokyo", "Beijing", "Hong Kong"]
searchEngine	Search	["google"]
socialNetwork	Social Media	["facebook"]
socialUrl	Social URL	["https://www.facebook.com/"]
aiName	AI Name	["ChatGPT", "Perplexity"]
referralSource	Referring website	["www.muji.com"]
referralUrl	Referral URL	["https://www.muji.com/"]
campaignUrl	Campaign URL	["https://www.google.com/"]
utmCampaign	Campaign name	["summer_sale"]
utmSource	Source	["google", "facebook"]
utmMedium	Medium	["cpc", "email"]
utmTerm	Term	["heatmap tool"]
utmContent	Content	["banner_a"]
combinedPages	Combined pages	["https://ptengine.jp/app/login"]
originalPages	Original pages	["https://ptengine.jp/app/select_project?from=login"]
conversionName	Conversion name	["ptmind"]
eventName	Event Name	["checkout_completed", "product_viewed"]
customDimension	Dimension	Requires eventVariant, see below
eventVariable	Dimension(Event Name)	Requires eventName and eventVariant, see below

Example: Query PC users from search engines

"filters": [
    { "name": "deviceType", "op": "include", "value": ["PC"] },
    { "name": "sourceType", "op": "include", "value": ["Search"] }
]

---

Query Available Filter Values

To check what values are available for a dynamic filter type:

POST /open-api/v1/heatmap/filter-values

Request body:

{
    "profileId": "566d12f9",
    "name": "os",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "search": ""
}

Parameter	Required	Description
profileId	Yes	Site ID
name	Yes	Filter type (e.g. country, browser, sourceType)
startDate	No	Start date, format: YYYY-MM-DD or YYYY/MM/DD, defaults to last 30 days
endDate	No	End date, format: YYYY-MM-DD or YYYY/MM/DD
search	No	Fuzzy search keyword

Example:

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

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "os",
        "values": ["Linux", "Mac OS X", "Windows", "iOS"]
    }
}

---

Custom Dimension Filter

Custom dimensions require a two-step process:

Step 1: Query custom dimension list

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

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "customDimension",
        "values": ["price", "sku", "currencycode"]
    }
}

Step 2: Query available values for a dimension

curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "customDimension",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "eventVariant": "price"
  }'

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "customDimension",
        "eventVariant": "price",
        "values": ["18900", "21900"]
    }
}

Use in query filter:

"filters": [
    {
        "name": "customDimension",
        "eventVariant": "price",
        "op": "include",
        "value": ["18900", "21900"]
    }
]

---

Dimension(Event Name) Filter

Custom dimensions require a three-step process:

Step 1: Query event custom dimension list

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

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventVariable",
        "values": [
            { "eventName": "product_viewed", "eventVariant": "price" },
            { "eventName": "product_viewed", "eventVariant": "currencycode" }
        ]
    }
}

Step 2: Query available values for a dimension

curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventVariable",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "eventName": "product_viewed",
    "eventVariant": "price"
  }'

Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventVariable",
        "eventName": "product_viewed",
        "eventVariant": "price",
        "values": ["18900", "21900"]
    }
}

Step 3: Use in query filter

"filters": [
    {
        "name": "eventVariable",
        "eventName": "product_viewed",
        "eventVariant": "price",
        "op": "include",
        "value": ["18900"]
    }
]

---

2.2 Query Types

2.2.1 page_metrics — Page-Level Metrics

Returns traffic, engagement, and conversion metrics for a specific page.

deviceType: Supports ALL, PC, MOBILE, TABLET

Metrics parameter: metrics (if not provided, returns all metrics)

Conversions: All query types support conversions. Add completions and/or conversionRate to metrics, and pass conversion goal names via conversionNames. The conversions array in the response will only include the conversion metrics you requested in metrics.

Example Request:

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": ["購入完了"],
    "lang": "EN"
  }'

Example Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": {
            "pv": {
                "value": "15,234",
                "label": "Page views (PV)",
                "description": "The number of times the page has been viewed."
            },
            "uv": {
                "value": "8,721",
                "label": "Unique visitors (UV)",
                "description": "The number of visitors who visited the page."
            },
            "visits": {
                "value": "10,532",
                "label": "Visits",
                "description": "The number of visits in which the page was viewed."
            },
            "bounceRate": {
                "value": "45.23%",
                "label": "% Bounce",
                "description": "The percentage of visits landed from the page and left without going to other pages."
            },
            "conversionRate": {
                "value": "2.22%",
                "label": "Conversion rate",
                "description": "The percentage of visits that the user viewed this page and complete the conversion in the same visit."
            }
        },
        "conversions": [
            {
                "conversionName": "購入完了",
                "conversionRate": {
                    "value": "1.71%",
                    "label": "Conversion rate",
                    "description": "The percentage of visits that the user viewed this page and complete the conversion in the same visit."
                }
            }
        ]
    },
    "meta": {
        "queryType": "page_metrics",
        "profileId": "566d12f9",
        "url": "https://ptengine.jp",
        "dateRange": { "start": "2025-06-01", "end": "2025-06-30" },
        "deviceType": "ALL",
        "lang": "EN"
    }
}

Note: The conversions array only returns the conversion metrics requested in metrics. In the example above, only conversionRate was requested, so completions is not included. To get both, add completions to metrics.

---

2.2.2 page_insight — Page Metrics by Dimension

Returns page metrics grouped by a specific dimension.

deviceType: Supports ALL, PC, MOBILE, TABLET

Required parameter: funName (metrics returns all if not provided)

funName options:

funName	Description
terminalType	Group by device type (PC/Smart phone/Tablet)
sourceType	Group by traffic source (Direct/Search/Social etc.)
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

Example Request (group by device type):

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"
  }'

Example Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "insights": [
            {
                "name": "PC",
                "metrics": {
                    "pv": { "value": "8,500", "label": "Page views (PV)", "description": "The number of times the page has been viewed." },
                    "uv": { "value": "5,200", "label": "Unique visitors (UV)", "description": "The number of visitors who visited the page." },
                    "bounceRate": { "value": "38.00%", "label": "% Bounce", "description": "The percentage of visits landed from the page and left without going to other pages." }
                },
                "conversions": []
            },
            {
                "name": "Mobile",
                "metrics": {
                    "pv": { "value": "5,800", "label": "Page views (PV)", "description": "The number of times the page has been viewed." },
                    "uv": { "value": "3,100", "label": "Unique visitors (UV)", "description": "The number of visitors who visited the page." },
                    "bounceRate": { "value": "55.00%", "label": "% Bounce", "description": "The percentage of visits landed from the page and left without going to other pages." }
                },
                "conversions": []
            },
            {
                "name": "Tablet",
                "metrics": {
                    "pv": { "value": "934", "label": "Page views (PV)", "description": "The number of times the page has been viewed." },
                    "uv": { "value": "421", "label": "Unique visitors (UV)", "description": "The number of visitors who visited the page." },
                    "bounceRate": { "value": "42.15%", "label": "% Bounce", "description": "The percentage of visits landed from the page and left without going to other pages." }
                },
                "conversions": []
            }
        ]
    }
}

---

2.2.3 block_metrics — Block-Level Metrics

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

deviceType: Must be PC, MOBILE, or TABLET. ALL is NOT supported.

metrics: Optional. If not provided, all metrics are returned. If provided, only specified metrics are returned. blockName and screenshotUrl are always returned.

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

stayTimeFilter: Optional, block stay time filter in seconds, default 5.

Example Request:

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"
  }'

Example Response:

{
    "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": "The number of page views that this block fully displayed." },
                    "impressionRate": { "value": "95.00%", "label": "Impression rate", "description": "The percentage of page views that the block fully displayed." },
                    "avgDuration": { "value": "5s", "label": "Avg. duration", "description": "The average duration that people who see and stay on this block." },
                    "dropoff": { "value": "800", "label": "Dropoff", "description": "The number of page views drop off after enter this block." },
                    "dropoffRate": { "value": "6.70%", "label": "Dropoff rate", "description": "The percentage of page views that drop off after entering this block." }
                },
                "conversions": []
            }
        ]
    }
}

---

2.2.4 element_metrics — Element-Level Metrics

Returns metrics for each tracked element on the page. Requires that the page has been scanned and elements configured in the product beforehand.

deviceType: Must be PC, MOBILE, or TABLET. ALL is NOT supported.

metrics: Optional. If not provided, all metrics are returned. If provided, only specified metrics are returned. elementName is always returned.

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

Example Request:

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"
  }'

Example Response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "elements": [
            {
                "elementName": "Sign Up Button",
                "metrics": {
                    "impression": { "value": "10,500", "label": "Impression", "description": "The number of page views that this element fully displayed." },
                    "impressionRate": { "value": "88.00%", "label": "Impression rate", "description": "The percentage of page views that the element fully displayed." },
                    "click": { "value": "1,500", "label": "Click", "description": "The number of clicks on this element." },
                    "clickRate": { "value": "14.30%", "label": "Click rate", "description": "The number of clicks divided by its impressions." }
                },
                "conversions": []
            }
        ]
    }
}

---

2.3 Available Metrics

2.3.1 Page Metrics (for page_metrics and page_insight)

Use these field names in the metrics array.

Traffic

Field	Description	Type
visits	The number of visits in which the page was viewed	value
pv	The number of times the page has been viewed	value
uv	The number of visitors who visited the page	value
newVisitsRate	The percentage of new visits that have viewed the page	rate
entrances	The number of visits that the page was visited as a landing page. You can know if this page is mainly used as a landing page	value

Engagement

Field	Description	Type
fvRate	The percentage of users who enter a page and do not scroll, convert, or go to the other page. A high FV drop-off rate means that the first screen of the page did not attract users to stay	rate
timeOnPage	The average duration on the page. You can know if the page content attracts visitors to stay longer	time
clicks	Total clicks on the page, no matter if there's a link or not	value
clickRate	The number of clicks per PV. You can use it to evaluate the user engagement with the page	rate
ctaClicks	The number of clicks on key CTAs within the page. You can set specific elements as CTAs in the heatmap	value
ctaClickRate	The click rate of key CTAs within the page. CTA click rate = CTA clicks / PV. You can set specific elements as CTAs in the heatmap	rate
bounceRate	The percentage of visits landed from the page and left without going to other pages. You can know if the page attracts users to visit further pages	rate
avgPageViews	The average number of pages visited after entering from this page. You can know the browsing depth on the site by users who landed from this page	decimal

Conversion

Field	Description	Type
completions	Number of visits that the user viewed this page and complete the conversion in the same visit	value
conversionRate	The percentage of visits that the user viewed this page and complete the conversion in the same visit. A higher conversion rate indicates this page played a stronger role in driving conversions	rate

Note: To get conversion data, you must also pass conversionNames with the names of your conversion goals.

---

2.3.2 Block Metrics (for block_metrics)

All metrics are returned when metrics is not provided. If provided, only specified metrics are returned. blockName and screenshotUrl are always returned.

Field	Description	Type
blockName	Name of the block	text
screenshotUrl	Block screenshot URL	text
impression	The number of page views that this block fully displayed	value
impressionRate	The percentage of page views that the block fully displayed	rate
dropoff	The number of page views drop off after enter this block, exclude users who click to a new page	value
dropoffRate	The percentage of page views that drop off after entering this block	rate
avgDuration	The average duration that people who see and stay on this block. A longer average duration usually means that the user is more interested in this block	time
completions	The number of visits where users spent a specified amount of time in each block and also converted	value
conversionRate	The percentage of visits where users spent a specified amount of time in each block and also converted	rate

---

2.3.3 Element Metrics (for element_metrics)

All metrics are returned when metrics is not provided. If provided, only specified metrics are returned. elementName is always returned.

Field	Description	Type
elementName	Name of the element	text
impression	The number of page views that the user starts to see the element on his screen	value
impressionRate	The percentage of page views that the user starts to see the element on his screen	rate
click	The number of clicks on this element	value
clickRate	The number of clicks divided by its impressions. A higher click rate means this element is more likely to attract clicks	rate
completions	The number of visits that clicked this element and also converted	value
conversionRate	The percentage of visits that clicked this element and also converted	rate

---

2.4 Device Type Rules

queryType	Allowed deviceType	Note
page_metrics	ALL, PC, MOBILE, TABLET	ALL returns combined data for all devices
page_insight	ALL, PC, MOBILE, TABLET	ALL returns combined data for all devices
block_metrics	PC, MOBILE, TABLET	ALL is NOT supported
element_metrics	PC, MOBILE, TABLET	ALL is NOT supported

---

2.5 Prerequisites for Block & Element Queries

Before using block_metrics or element_metrics, the page must be scanned and configured in the Ptengine product:

1. Open the page in Ptengine Heatmap

2. Enable block/element detection

3. Save the configuration

If the page has not been configured, the API will return error code 4008 (blocks) or 4016 (elements).

---

2.6 Complete Examples

Example 1: Get page traffic overview

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: Get page insights by device type

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: Get mobile block analysis

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",
    "lang": "EN"
  }'

Example 4: Get conversion data for specific goals

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": ["購入完了"],
    "lang": "EN"
  }'

Example 5: Get PC element click analysis

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": "JP"
  }'

---

2.7 Notes

• All timestamps in responses are in milliseconds.

• Time-type fields such as timeOnPage (page) and avgDuration (block) are returned as a human-readable string with unit (e.g. "5s", "1m 30s").

• Rate values (e.g., bounceRate, clickRate) are decimal numbers (0.45 = 45%).

• conversionNames uses fuzzy matching — partial names will match.

• The API uses the same data source as the Ptengine product UI, so results should be consistent.

• If the requested URL has never been tracked under this profile, the API returns 200 with all metric values set to 0 (not an error).

---

3. Experience Data Query

3.1 Get Experience List

POST /open-api/v1/experience/list

Retrieves basic information for all experiences under the current profile, including goals and version lists. The id, goalId, and versionId used in subsequent APIs all come from this endpoint's response.

Request body:

{
    "profileId": "566d12f9"
}

Parameter	Required	Description
profileId	Yes	Site ID

Example response:

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

Response Field	Description
id	Experience ID, used as the id parameter in report APIs
name	Experience name
status	Status: DRAFT / RUNNING / PAUSE / SCHEDULED
type	Type: POPUP / STICKY_BAR / INLINE / ADVANCED / REDIRECT
goals	Goal list, used as the goalId parameter in A/B test APIs
versions	Version list, used as the versionId parameter in form APIs

---

3.2 Get User Properties List

POST /open-api/v1/experience/user-properties

Retrieves the list of available user properties. When the dimension breakdown API's dimension is userProperty, you need to obtain the property parameter from this endpoint.

Request body:

{
    "profileId": "566d12f9"
}

Example response:

{
    "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

POST /open-api/v1/experience/report/overview

Query metrics data for multiple experiences in bulk.

Request body:

{
    "profileId": "566d12f9",
    "experiences": [
        { "id": "6c3bad4b-...", "name": "Spring Sale Popup" },
        { "id": "5bb77b97-...", "name": "Signup Guide" }
    ],
    "metrics": ["viewedUsers", "clickRate", "bounceRate"],
    "lang": "EN"
}

Parameter	Required	Description
profileId	Yes	Site ID
experiences	Yes	Experience list (id + name, from the list API)
metrics	No	Metric fields to return. If not provided, all default metrics are returned. See the metrics table below for supported fields
lang	No	Response language: EN (default), ZH, JP

Supported metrics fields:

Field	Description	Type
viewedUsers	The number of users who viewed the experience	value
views	The number of times the experience has been viewed	value
clickedUsers	The number of users that clicked the button or link in the experience	value
clickRate	The percentage of users that clicked the button or link in the experience	rate
closedUsers	The number of users that closed popup or sticky bar	value
closeRate	The percentage of users that closed popup or sticky bar	rate
formSubmittedUsers	The number of users that submitted the form in the experience	value
formSubmitRate	The percentage of users that submitted the form in the experience	rate
goalReachedUsers	The number of users that completed the goal after viewing the experience	value
goalReachRate	The percentage of users that completed the goal after viewing the experience	rate
goalStatus	Display goal achievement by user percentage, property sum, or average	value
avgVisitDuration	The average visit duration that users viewed the experience	time
avgPagesPerVisit	The average pages per visit that users viewed the experience	decimal
bounceRate	The bounce rate of the visit that users viewed the experience	rate
lastUpdatedTime	Last updated time of the experience	text
lastUpdatedMember	The experience was last updated by	text
createdTime	The time this experience was created	text
createdMember	The member who created the experience	text
runningPeriod	The period of time the experience has been running	text
tags	Custom attribute tags for each experience	text

Example response:

{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "name": "Spring Sale Popup",
            "viewedUsers": { "value": 100, "label": "Viewed Users", "description": "The number of users the experience was shown to." },
            "clickRate": { "value": "5.00%", "label": "Click Rate", "description": "The percentage of users who clicked a button or link in the experience." },
            "bounceRate": { "value": "42.86%", "label": "Bounce Rate", "description": "The bounce rate of visits where the experience was shown." }
        }
    ]
}

All metrics return a { value, label, description } structure, where label and description are localized according to lang.

---

3.4 Key Metrics

POST /open-api/v1/experience/report/metrics

Query overall metrics for a single experience.

Request body:

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "lang": "EN"
}

Parameter	Required	Description
profileId	Yes	Site ID
id	Yes	Experience ID
startDate	Yes	Start date, format: YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	End date, format: YYYY-MM-DD or YYYY/MM/DD
lang	No	Response language

Example response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Sale 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 Completed",
                        "reachedUsers": { "value": 5, "label": "Goal Reached Users", "description": "..." },
                        "reachRate": { "value": "5.00%", "label": "Goal Reach Rate", "description": "..." },
                        "value": { "value": null, "label": "Goal Value", "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: The returned metrics are automatically filtered based on the experience type. For example, INLINE types will not return clickedUsers / closedUsers, and experiences without forms will not return formSubmittedUsers.

---

3.5 Breakdown Details

POST /open-api/v1/experience/report/insight

Query metrics for a single experience grouped by dimension.

Request body:

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "dimension": "terminalType",
    "subDimension": "visitType",
    "lang": "EN"
}

Parameter	Required	Description
profileId	Yes	Site ID
id	Yes	Experience ID
startDate	Yes	Start date, format: YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	End date, format: YYYY-MM-DD or YYYY/MM/DD
dimension	Yes	Primary dimension, see dimension table below
subDimension	No	Secondary dimension
property	Conditional	Required when dimension is userProperty, obtained from the user-properties API
lang	No	Response language

dimension options:

dimension	Description	Supports subDimension
visitPage	Page	No
terminalType	Device type	Yes
sourceType	Traffic source	Yes
utmCampaign	Campaign name	Yes
utmSource	Campaign source	Yes
utmMedium	Campaign medium	Yes
utmTerm	Campaign term	Yes
utmContent	Campaign content	Yes
sourceUrl	Source URL	Yes
sourceHost	Source domain	Yes
aiName	AI name	Yes
visitType	New/returning visit	Yes
country	Country/region	Yes (cannot combine with region)
region	Region	Yes (cannot combine with country)
userProperty	User property	No (requires property)

userProperty example:

{
    "dimension": "userProperty",
    "property": { "name": "plan_name", "source": ["code"], "type": "STRING" }
}

Example response:

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

---

3.6 A/B Testing Results

POST /open-api/v1/experience/report/abtest/metrics

Query metric comparison data across A/B test versions, including uplift and probability to be best.

Request body:

{
    "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"
}

Parameter	Required	Description
profileId	Yes	Site ID
id	Yes	Experience ID
startDate	Yes	Start date, format: YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	End date, format: YYYY-MM-DD or YYYY/MM/DD
compareBy	Yes	Comparison metric for version comparison, see below
goalId	Conditional	Required when compareBy is goalReached (obtained from the goals in the list API)
showDeletedVersions	No	Whether to include deleted versions, defaults to false
lang	No	Response language

compareBy options:

compareBy	Description
viewedUsers	The number of users who viewed the experience
clickedUsers	The number of users that clicked the button or link in the experience
closedUsers	The number of users that closed popup or sticky bar
formSubmittedUsers	The number of users that submitted the form in the experience
goalReached	Goal reached (requires goalId)
avgVisitDuration	Average visit duration
avgPagesPerVisit	Average pages per visit
bounceRate	The bounce rate of the visit that users viewed the experience

Example response:

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

• The response only includes the metrics corresponding to compareBy plus uplift and probabilityToBeBest

• The baseline version's uplift value is "Baseline", while other versions show a percentage (e.g., "+50.00%" or "-10.00%")

---

3.7 A/B Testing Results — Breakdown Details

POST /open-api/v1/experience/report/abtest/insight

Metric comparison across A/B test versions grouped by dimension.

Request body:

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-...",
    "dimension": "terminalType",
    "lang": "EN"
}

Parameter	Required	Description
profileId	Yes	Site ID
id	Yes	Experience ID
startDate	Yes	Start date, format: YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	End date, format: YYYY-MM-DD or YYYY/MM/DD
compareBy	Yes	Comparison metric (same as 3.6)
goalId	Conditional	Required when compareBy is goalReached
dimension	Yes	Primary dimension (same as 3.5)
subDimension	No	Secondary dimension
property	Conditional	Required when dimension is userProperty
showDeletedVersions	No	Whether to include deleted versions, defaults to false
lang	No	Response language

Example response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "Spring Sale 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 Submission

POST /open-api/v1/experience/report/form

Query form submission detail data for a specific version.

Request body:

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "versionId": "a2696719-6375-456b-8dbc-7e3d273beb6d",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
}

Parameter	Required	Description
profileId	Yes	Site ID
id	Yes	Experience ID
versionId	Yes	Version ID (from the versions in the list API)
startDate	Yes	Start date, format: YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	End date, format: YYYY-MM-DD or YYYY/MM/DD

Example response:

{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": ["submittedAt", "Email", "Picture choice", "choice-test2"],
        "rows": [
            {
                "submittedAt": "2026/04/09 19:14:33",
                "Email": "[email protected]",
                "Picture choice": "Option 3",
                "choice-test2": ""
            },
            {
                "submittedAt": "2026/04/08 17:40:05",
                "Email": "[email protected]",
                "Picture choice": "",
                "choice-test2": "Option 1,Option 2"
            }
        ]
    }
}

• columns contains dynamic headers, automatically generated based on the actual form fields

• Each entry in rows represents one form submission; fields without values are empty strings

---

3.9 Available Metrics

Base Metrics (supported by all types)

Field	Format	Description
viewedUsers	Number	Number of users the experience was shown to
views	Number	Number of times the experience was shown
avgVisitDuration	Duration (MM:SS/HH:MM:SS)	Average visit duration
avgPagesPerVisit	Decimal ("2.50")	Average pages per visit
bounceRate	Percentage ("42.86%")	Bounce rate

Popup Metrics (POPUP / STICKY_BAR / REDIRECT / ADVANCED with popup only)

Field	Format	Description
clickedUsers	Number	Number of users who clicked
clickRate	Percentage	Click rate
closedUsers	Number	Number of users who closed
closeRate	Percentage	Close rate

Form Metrics (only for experiences with forms configured)

Field	Format	Description
formSubmittedUsers	Number	Number of users who submitted the form
formSubmitRate	Percentage	Form submission rate

Goal Data

Field	Description
goals[].name	Goal name
goals[].reachedUsers	Number of users who reached the goal
goals[].reachRate	Goal reach rate
goals[].value	Goal value (null = counted by users)

---

4. Event Data Query

Custom event analytics. Equivalent to the dimensions/metrics available on the Ptengine Event > Segment page (/event/segment).

4.1 Query Custom Event Data

POST /open-api/v1/event/query

Query event data by combining any number of dimensions, metrics, filters and custom event property filters.

Request body:

Field	Required	Type	Description
profileId	Yes	string	Profile (site) id
startDate	Yes	string	YYYY-MM-DD or YYYY/MM/DD
endDate	Yes	string	YYYY-MM-DD or YYYY/MM/DD
dimensions	Yes	(string | object)[]	Grouping dimensions. Must include the string "eventName". Limit: max 3 non-time dimensions + at most 1 time dimension (day / hour / week / month) — matches the product /event/segment page. Each item is either a string (standard dimension name) or { name: "eventVariable", eventVariant: "<propName>" } for custom event properties.
metrics	No	string[]	Metric field names. Defaults to ["eventCount"]. Allowed: eventCount, sessions
filters	No	object[]	Filter conditions, identical shape to /heatmap/query: { name, op, value, eventName?, eventVariant? }

Filter operators: include / exclude (same as /heatmap/query). value must be a non-empty array (e.g. ["Japan"], ["Japan", "China"]).

Custom event property:

• In dimensions: { name: "eventVariable", eventVariant: "<propName>" }

• In filters: { name: "eventVariable", eventName: "<event>", eventVariant: "<propName>", op, value } — same shape as /heatmap/query's eventVariable filter.

• When you use an eventVariable filter, also pass { name: "eventName", op: "include", value: ["<event>"] } (matches the product /event/segment page).

In the response, the column name is the bare property name.

Example request:

{
    "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": "eventVariable",   "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100", "200"] }
    ]
}

Example response:

{
    "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": "click_buy", "day": "2026-04-15", "country": "Japan", "eventCount": 320, "sessions": 250 }
        ]
    }
}

4.2 More Examples

a) Minimal — count events per name

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"]
}

b) Time series — events per day

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day"],
    "metrics": ["eventCount", "sessions"]
}

c) Filter by conversion goal (fuzzy name match)

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "conversionName"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",      "op": "include", "value": ["click_buy"] },
        { "name": "conversionName", "op": "include", "value": ["ptmind"] }
    ]
}

conversionName matches any goal whose name contains "ptmind". Returns 4012 if no goals match.

d) Custom event property — group + filter

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": [
        "eventName",
        { "name": "eventVariable", "eventVariant": "position" }
    ],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",     "op": "include", "value": ["gallery_item_impression"] },
        { "name": "eventVariable", "eventName": "gallery_item_impression", "eventVariant": "position",
          "op": "include", "value": ["home"] }
    ]
}

Both filters are required and play different roles: the standalone eventName filter pins the query to the gallery_item_impression event (aggregation scope); the eventVariable filter further narrows results to rows where position == "home" (segment).

e) Source breakdown — UTM + traffic source

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "sourceType", "utmSource"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "eventName",  "op": "include", "value": ["click_buy"] },
        { "name": "sourceType", "op": "include", "value": ["Search", "Campaign"] }
    ]
}

f) New visitors on PC, in Japan / China

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "country"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",  "op": "include", "value": ["click_buy"] },
        { "name": "visitType",  "op": "include", "value": ["New visits"] },
        { "name": "deviceType", "op": "include", "value": ["PC"] },
        { "name": "country",    "op": "include", "value": ["Japan", "China"] }
    ]
}

g) Exclude bounced sessions

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "exitType", "op": "exclude", "value": ["Bounce visits"] }
    ]
}

4.3 List Available Fields

GET /open-api/v1/event/fields?lang=EN

Returns supported metrics, dimensions, and operators with localized labels.

4.4 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

4.5 Available Dimensions (for dimensions[] group-by)

Field names follow the same vocabulary as /heatmap/query filters.

Category	Field	Description
event	eventName	Event name
visit	visitType	New visits / Returning visits
visit	exitType	Bounce visits / Non-bounce visits
page	originalPages	Entry page (full URL)
page	combinedPages	Entry page (without query string)
conversion	conversionName	Conversion goal name
time	day	Date YYYY-MM-DD
time	hour	Hour 0–23
time	week	ISO week
time	month	Year-month YYYY-MM
source	sourceType	Direct / Search / Social / Referral / Campaign / AISearch
source	campaignUrl	Campaign landing URL
source	referralSource	Referral host
source	referralUrl	Referral URL
source	searchEngine	Search engine
source	socialNetwork	Social network
source	socialUrl	Social URL
source	aiName	AI search engine
ad	utmCampaign / utmSource / utmMedium / utmTerm / utmContent	UTM fields
terminal	deviceType	PC / Mobile / Tablet
terminal	deviceBrand	Device brand
terminal	os / osVersion / browser / browserVersion	OS / browser + versions
terminal	screenResolution	Screen resolution
geography	country / region	Country / state

4.6 Available Filter Fields (for filters[])

Field names AND values are identical to /heatmap/query. Differences from the dimension list above: no time fields; plus eventVariable for custom event properties. conversionName performs fuzzy name matching (server resolves to conversion goal IDs).

Fixed-value enums (must use the listed values exactly):

Field	Allowed values
visitType	New visits, Returning visits
exitType	Bounce visits, Non-bounce visits
deviceType	PC, Mobile, Tablet
sourceType	Direct, Search, Social, Referral, Campaign, AISearch

Full filter field list:

Category	Field	Description
visit	visitType / exitType	See enum table
visit	originalPages / combinedPages	Entry page (full URL / without query)
source	sourceType	See enum table
source	campaignUrl	Campaign landing URL
source	referralSource / referralUrl	Referral host / URL
source	searchEngine	Search engine
source	socialNetwork / socialUrl	Social network / URL
source	aiName	AI search engine
terminal	deviceType / deviceBrand	See enum table / brand
terminal	os / osVersion / browser / browserVersion	OS / browser + versions
terminal	screenResolution	Resolution
geography	country / region	Country / state
conversion	conversionName	Conversion goal name (fuzzy match, e.g. ["ptmind"] matches all goals containing "ptmind")
campaign	utmCampaign / utmSource / utmMedium / utmTerm / utmContent	UTM fields
event	eventName	Event name
custom	eventVariable	{ name: "eventVariable", eventName: "<event>", eventVariant: "<propName>" } — same shape as /heatmap/query filter

4.7 Custom Event Properties

The Ptengine SDK can report custom event properties along with each event. The Open API uses two slightly different forms for dimensions vs filters:

• In dimensions: { "name": "eventVariable", "eventVariant": "<propName>" }

• In filters: { "name": "eventVariable", "eventName": "<event>", "eventVariant": "<propName>", "op": "include"|"exclude", "value": [...] } — same shape as /heatmap/query's eventVariable filter.

• When you use an eventVariable filter, also pass { "name": "eventName", "op": "include", "value": ["<event>"] }. Missing it returns 4018.

In the response, the column name is the bare property name (e.g. "price").

{
    "dimensions": [
        "eventName",
        { "name": "eventVariable", "eventVariant": "price" }
    ],
    "filters": [
        { "name": "eventName",     "op": "include", "value": ["purchase"] },
        { "name": "eventVariable", "eventName": "purchase", "eventVariant": "category", "op": "include", "value": ["shoes"] }
    ]
}

4.8 Notes

• visitType, exitType, deviceType, sourceType only accept the fixed enum values listed in §4.6 — pass them exactly as listed.

• dimensions is required and must include the string "eventName" (mirrors the product /event/segment page, which always groups by event name). You can add other dimensions / eventVariable objects alongside it.

• Dimension count limit: at most 3 non-time dimensions + 1 time dimension (day / hour / week / month). Exceeding either limit returns 4018. This matches the product /event/segment page.

• When an eventName filter is required — any of the following triggers it:

  • dimensions has a non-time dimension other than "eventName" (e.g. country, sourceType)

  • dimensions has an eventVariable object

  • filters has an eventVariable filter

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

• The order of columns in the response follows the order returned by the backend, not necessarily the order you requested.

---

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 API key
4031	403	API key does not have query permission. Required scope: query
4001	400	Invalid queryType
4002	400	Invalid date format, expected YYYY-MM-DD or YYYY/MM/DD
4003	400	Query date exceeds data storage limit of your plan
4006	400	funName is required for page_insight
4007	400	block_metrics requires specific deviceType (PC/MOBILE/TABLET)
4008	400	Page blocks not configured — scan the page first
4009	400	element_metrics requires specific deviceType (PC/MOBILE/TABLET)
4012	400	No conversions found matching the provided names
4013	400	Missing required field (the response message indicates which field is missing)
4014	400	Invalid deviceType. Must be one of: ALL, PC, MOBILE, TABLET
4015	400	Invalid dimension / subDimension (the response message indicates the exact reason)
4016	400	Page elements not configured — scan the page first
4017	400	Invalid compareBy (the response message lists allowed values)
4018	400	Invalid event field (/event/query: dimension or metric not in the supported list)
4019	400	Invalid filter operator (/event/query: must be include or exclude)
4040	404	Experience not found (the 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 localized based on the request's lang (body or query). Defaults to English when lang is omitted or not in EN/ZH/JP.

Error Response Format:

{
    "code": 4007,
    "message": "block_metrics requires specific deviceType (PC/MOBILE/TABLET), ALL is not supported"
}