Get Chart
Returns chart data for the given funnel, subtype, and time window.
GET /v1/funnels/{funnelId}/metrics/charts/{subtype}
Authentication
Requires the x-perspective-api-key header. See Authentication for details.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
funnelId | string | Yes | The ID of the funnel to query. |
subtype | string | Yes | The chart type to retrieve. See Valid chart subtypes below. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (ISO 8601) | Yes | Start of the metrics period, e.g. 2025-01-01T00:00:00.000Z. Must be before to. |
to | string (ISO 8601) | Yes | End of the metrics period, e.g. 2025-01-31T00:00:00.000Z. |
offset | string | No | Timezone offset in minutes, e.g. -120 for UTC−2. Accepts an optional leading + or -. |
abTest | string | No | A/B test filter. Only valid for chart_page_to_page_conversion_rate. Accepted values: all, original, variant. Passing this parameter for any other subtype returns a 400 error. |
Valid chart subtypes
subtype | What it measures |
|---|---|
chart_page_to_page_conversion_rate | Conversion rate between each consecutive page in the funnel. Supports A/B test filtering via abTest. |
chart_activity_by_daytime | Visitor activity heatmap by day of week and hour of day. |
chart_contacts_over_time | Number of new contacts over time (daily or monthly granularity). |
chart_visitor_devices | Visitor breakdown by device type (mobile, desktop, tablet, other). |
chart_top_utm_sources | Top traffic sources based on UTM parameters. |
chart_time_on_page | Average time spent on each page of the funnel. |
chart_button_clicks | Click counts for each button in the funnel. |
chart_top_utm_mediums, chart_top_utm_campaigns, chart_top_utm_terms, chart_top_utm_contents, chart_top_utm_ids | Visitor sessions per value of that UTM field of the landing URL, every value included. Values are text, such as ad ids or names, exactly as the ad set them. At most 180 days per request. |
chart_utm_source_conversions, chart_utm_medium_conversions, chart_utm_campaign_conversions, chart_utm_term_conversions, chart_utm_content_conversions, chart_utm_id_conversions | Visits, conversions and conversion rate per value of that UTM field. Each session counts once, under the value of its first visit in the range. At most 180 days per request. |
Example request
- cURL
- JavaScript
curl "https://api.perspective.co/v1/funnels/fnl_abc123/metrics/charts/chart_page_to_page_conversion_rate?from=2025-01-01T00:00:00.000Z&to=2025-01-31T00:00:00.000Z" \
-H "x-perspective-api-key: $PERSPECTIVE_API_KEY"
const funnelId = 'fnl_abc123';
const subtype = 'chart_page_to_page_conversion_rate';
const params = new URLSearchParams({
from: '2025-01-01T00:00:00.000Z',
to: '2025-01-31T00:00:00.000Z',
});
const response = await fetch(
`https://api.perspective.co/v1/funnels/${funnelId}/metrics/charts/${subtype}?${params}`,
{
headers: {
'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
},
}
);
const { data } = await response.json();
Response
Returns { data: ChartDataPoint[] }.
ChartDataPoint object
| Field | Type | Description |
|---|---|---|
key | string | Identifier or label for the data point (e.g. a time slot, device type, or page slug). |
value | number | Numeric value for the data point (e.g. a count or duration). |
name | string | Human-readable display name (e.g. the page name). Present only on some chart types. |
relativeValue | number | Relative value as a ratio between 0 and 1 (e.g. 0.25 = 25%). Present only on some chart types. |
conversions | number | Sessions with this value that converted (became contacts). Only on the chart_utm_*_conversions charts. |
conversionRate | number | conversions / value, in percent. Only on the chart_utm_*_conversions charts. |
Example responses
Page-to-page conversion rate (chart_page_to_page_conversion_rate)
{
"data": [
{
"key": "homepage",
"value": 1000,
"name": "Homepage",
"relativeValue": 0.25
},
{
"key": "product-page",
"value": 500,
"name": "Product Page",
"relativeValue": 0.45
}
]
}
Activity by daytime (chart_activity_by_daytime)
{
"data": [
{ "key": "MON 09:00", "value": 100, "relativeValue": 0.44 },
{ "key": "MON 17:00", "value": 50, "relativeValue": 0.22 },
{ "key": "TUE 13:00", "value": 75, "relativeValue": 0.33 }
]
}
Visitor devices (chart_visitor_devices)
{
"data": [
{ "key": "mobile", "value": 300, "relativeValue": 0.3 },
{ "key": "desktop", "value": 500, "relativeValue": 0.5 },
{ "key": "tablet", "value": 150, "relativeValue": 0.15 },
{ "key": "other", "value": 50, "relativeValue": 0.05 }
]
}
Errors
See Errors for the full list of status codes and handling guidance.
| Status | Meaning |
|---|---|
400 | Missing or invalid parameters, the requested chart type was not found, abTest was supplied for a subtype that does not support it, or a UTM field chart was asked for more than 180 days. |
401 | Missing or invalid API key. |
403 | Your API key does not have metrics:read permission. |
500 | Internal server error. |