Get KPI

Returns a single Key Performance Indicator (KPI) for the given funnel and time window.

GET /v1/funnels/{funnelId}/metrics/kpis/{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 KPI type to retrieve. See Valid KPI 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 -.

Valid KPI subtypes

subtype	What it measures	Unit
kpi_conversion_rate	Percentage of visitors who convert (become contacts)	%
kpi_completion_rate	Percentage of visitors who complete the entire funnel	%
kpi_average_time_on_page	Average time visitors spend on each page	seconds
kpi_time_to_completion	Average time from first page view to funnel completion	seconds
kpi_new_contacts	Number of new contacts created in the period	count
kpi_total_sessions	Total number of visitor sessions in the period	count
kpi_messages_sent	Total number of automated messages sent in the period	count
kpi_messages_delivery_rate	Percentage of automated messages delivered to contacts	%
kpi_messages_open_rate	Percentage of automated messages opened by contacts	%

Example request

cURL

curl "https://api.perspective.co/v1/funnels/fnl_abc123/metrics/kpis/kpi_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 = 'kpi_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/kpis/${subtype}?${params}`,
  {
    headers: {
      'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
    },
  }
);

const { data } = await response.json();

Response

Returns { data: KpiData }.

KpiData object

Field	Type	Description
type	string	The KPI subtype name in camelCase (e.g. kpiConversionRate).
value	number	The computed KPI value. For rate-based KPIs (e.g. kpi_conversion_rate, kpi_completion_rate, kpi_messages_delivery_rate, kpi_messages_open_rate) this is a percentage. For time-based KPIs (e.g. kpi_average_time_on_page, kpi_time_to_completion) this is a duration in seconds. For count-based KPIs (e.g. kpi_new_contacts, kpi_total_sessions, kpi_messages_sent) this is a raw integer count.
count	number	Total number of events or occurrences used to compute a rate-based KPI. Present only for rate-based KPIs.

Example response

{
  "data": {
    "type": "kpiConversionRate",
    "value": 12.5,
    "count": 150
  }
}

Errors

See Errors for the full list of status codes and handling guidance.

Status	Meaning
400	Missing or invalid parameters, or the requested KPI type was not found for this funnel.
401	Missing or invalid API key.
403	Your API key does not have metrics:read permission.
500	Internal server error.