Skip to main content

Metrics and Analytics

Perspective exposes three types of analytics data through the API: KPIs, charts, and insights. Each one answers a different category of question about how your funnels are performing. All three are scoped to a funnel and require a date range.

KPIs: single-number summaries​

A KPI (Key Performance Indicator) gives you one computed number for a funnel over a time window. Use KPIs when you want a top-line answer: "What was my conversion rate last month?" or "How many new contacts did this funnel generate?"

The available KPI subtypes include:

  • Conversion and completion rates — what percentage of visitors converted into contacts (kpi_conversion_rate) or completed the entire funnel (kpi_completion_rate)
  • Session counts — total visitor sessions (kpi_total_sessions) and new contacts (kpi_new_contacts) in the period
  • Time metrics — average time spent per page (kpi_average_time_on_page) and time from first page view to completion (kpi_time_to_completion), both in seconds
  • Messaging metrics — messages sent (kpi_messages_sent), delivery rate (kpi_messages_delivery_rate), and open rate (kpi_messages_open_rate) for automated outreach

Each KPI returns a value (a percentage, count, or duration) and, for rate-based KPIs, a count showing the number of events used to compute the rate. See Get KPI for the full list of subtypes, units, and an example response.

Charts: time series and breakdowns​

Charts return arrays of data points rather than a single number. Use charts when you need to visualize trends, diagnose drop-off, or understand your audience composition.

The available chart subtypes cover:

  • Page-to-page conversion rate (chart_page_to_page_conversion_rate) — the drop-off (and recovery) between each consecutive page in the funnel. This is the primary tool for identifying which step is losing visitors.
  • Activity by daytime (chart_activity_by_daytime) — a heatmap of visitor activity by day of week and hour. Useful for scheduling email sends or ad spend.
  • Contacts over time (chart_contacts_over_time) — new contacts at daily or monthly granularity. Good for spotting campaign spikes or seasonality.
  • Visitor devices (chart_visitor_devices) — mobile, desktop, tablet, and other. Essential for deciding how to prioritize mobile optimization.
  • Top UTM sources (chart_top_utm_sources) — which traffic sources are driving the most visits, based on UTM parameters.
  • Time on page (chart_time_on_page) — average time per page, useful for diagnosing pages where visitors are disengaging or rushing.
  • Button clicks (chart_button_clicks) — click counts for individual buttons in the funnel.

Each data point in a chart response has a key (identifier or label), a value (the raw number), and optionally name (human-readable label) and relativeValue (a 0–1 ratio). See Get Chart for the full response shape.

A/B test filtering​

The page-to-page conversion rate chart supports an optional abTest query parameter with values all, original, or variant. This lets you compare how different versions of the funnel perform across the same date range. Passing abTest on any other chart subtype returns a 400 error.

Insights: question-level response data​

Insights drill into the answers your contacts gave to individual funnel questions. Each insight is identified by a question ID (the insightId, visible in the Perspective funnel builder). The response shows how many respondents chose each answer option.

For multiple-choice questions, the response also includes groupedAnswers — a breakdown of the exact combinations of answers respondents selected together. This is useful for understanding which answer combinations correlate with conversion.

Insights are particularly powerful when combined with contact and KPI data: you can identify which answer segments convert best, and use that to refine your funnel copy or targeting.

See Get Insight for the response schema and an example.

Date ranges and timezones​

All three metric types require from and to query parameters as ISO 8601 timestamps (for example, 2025-01-01T00:00:00.000Z). The from timestamp must be before to.

An optional offset parameter accepts a timezone offset in minutes (for example, -120 for UTC−2). Use this when you want results aligned to a local timezone rather than UTC.

Metrics via MCP​

For AI assistants and conversational analytics workflows, the MCP server provides tools that wrap these same metrics endpoints. An AI agent can ask questions like "What was the conversion rate on the summer campaign funnel last month?" and the MCP tool will handle parameter construction and return the result in a readable format.

See the MCP Metrics tools and MCP Sequence Stats tools for the available tools.

Permissions​

All metrics endpoints require metrics:read permission on your API key. See API Keys for how to configure permissions.