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.

Example request

cURL

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"

JavaScript

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.

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, or abTest was supplied for a subtype that does not support it.
401	Missing or invalid API key.
403	Your API key does not have metrics:read permission.
500	Internal server error.