Skip to main content

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​

NameTypeRequiredDescription
funnelIdstringYesThe ID of the funnel to query.
subtypestringYesThe chart type to retrieve. See Valid chart subtypes below.

Query parameters​

NameTypeRequiredDescription
fromstring (ISO 8601)YesStart of the metrics period, e.g. 2025-01-01T00:00:00.000Z. Must be before to.
tostring (ISO 8601)YesEnd of the metrics period, e.g. 2025-01-31T00:00:00.000Z.
offsetstringNoTimezone offset in minutes, e.g. -120 for UTC−2. Accepts an optional leading + or -.
abTeststringNoA/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​

subtypeWhat it measures
chart_page_to_page_conversion_rateConversion rate between each consecutive page in the funnel. Supports A/B test filtering via abTest.
chart_activity_by_daytimeVisitor activity heatmap by day of week and hour of day.
chart_contacts_over_timeNumber of new contacts over time (daily or monthly granularity).
chart_visitor_devicesVisitor breakdown by device type (mobile, desktop, tablet, other).
chart_top_utm_sourcesTop traffic sources based on UTM parameters.
chart_time_on_pageAverage time spent on each page of the funnel.
chart_button_clicksClick 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_idsVisitor 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_conversionsVisits, 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 "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"

Response​

Returns { data: ChartDataPoint[] }.

ChartDataPoint object​

FieldTypeDescription
keystringIdentifier or label for the data point (e.g. a time slot, device type, or page slug).
valuenumberNumeric value for the data point (e.g. a count or duration).
namestringHuman-readable display name (e.g. the page name). Present only on some chart types.
relativeValuenumberRelative value as a ratio between 0 and 1 (e.g. 0.25 = 25%). Present only on some chart types.
conversionsnumberSessions with this value that converted (became contacts). Only on the chart_utm_*_conversions charts.
conversionRatenumberconversions / 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.

StatusMeaning
400Missing 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.
401Missing or invalid API key.
403Your API key does not have metrics:read permission.
500Internal server error.