Get Insight

Returns aggregated response data for a specific funnel question or survey element.

GET /v1/funnels/{funnelId}/metrics/insights/{insightId}

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.
insightId	string	Yes	The ID of the question or survey element, as shown in the funnel builder (e.g. question_1234).

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 -.

Example request

cURL

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

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

Response

Returns { data: InsightData }.

InsightData object

Field	Type	Description
title	string	The question text for this insight.
answers	object	Map of answer text to response count. Each key is an answer option; the value is how many respondents chose it.
groupedAnswers	object	Present only for multiple-choice questions. Keys are semicolon-separated answer combinations (e.g. "Option A; Option B"); values are the count of respondents who selected that exact combination.

Example response

{
  "data": {
    "title": "What is your Community goal? Answer the question to find the right course for you and receive optimal support.",
    "answers": {
      "Secure competitive advantage": 3,
      "Receive support": 1,
      "Gain loyal fans": 1
    },
    "groupedAnswers": {
      "Secure competitive advantage; Receive support": 4,
      "Receive support; Gain loyal fans": 2
    }
  }
}

Errors

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

Status	Meaning
400	Missing or invalid parameters, or the requested insight 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.