Reports API

Reports API

The Reports API provides access to current read-only survey metadata, aggregate response summaries, usage summaries, and raw response rows for the tenant. Endpoints require one of the current integration scopes: ReportsRead, UsageRead, or RawResponsesRead.

Required Scope

ReportsRead for survey metadata and response summaries. UsageRead for usage summaries. RawResponsesRead for raw response rows, individual answer values, and authorized response-file downloads.

Authentication also requires an active tenant and allowed subscription access, the client remaining within the effective External integrations, and the matching plan capability. ReportsRead and UsageRead require Report API access; RawResponsesRead requires Raw response API access. A failed authentication or plan gate returns HTTP 401. An authenticated key that lacks an endpoint's required scope returns HTTP 403.

Available Endpoints

List Survey Metadata

Returns one unpaged array of all non-deleted tenant survey metadata, ordered by name.

GET /api/integrations/reports/surveys

Response fields (per survey):

List Aggregate Response Summaries

Returns one unpaged array of aggregate response counts grouped by surveys that have non-deleted responses.

GET /api/integrations/reports/responses

Response fields include surveyId, nullable surveyName, totalResponses, completedResponses, and nullable lastResponseAt.

Response example:

[
  {
    "surveyId": 45,
    "surveyName": "Customer Satisfaction",
    "totalResponses": 342,
    "completedResponses": 310,
    "lastResponseAt": "2026-07-20T14:22:11Z"
  }
]

Get Usage Summary

Returns active client, total client, active survey, and current-month response counts.

GET /api/integrations/reports/usage

{
  "activeClients": 2,
  "totalClients": 3,
  "activeSurveys": 5,
  "responsesThisMonth": 342
}

List Raw Response Rows

Returns current raw response metadata in a bare paged array. This endpoint requires RawResponsesRead; it exposes response/file metadata and answer counts, not answer values.

GET /api/integrations/reports/raw-responses?page=1&pageSize=50

Rows are ordered by createdAt descending and then unique id descending.

Get One Response's Answers

Returns the actual answer values for one current tenant response. File answers include safe file references; file bytes remain on the separate download route.

GET /api/integrations/reports/raw-responses/{responseId}/answers

This endpoint requires RawResponsesRead and preserves tenant opacity: a response outside the key's tenant is not disclosed.

Contract Boundary

Report summaries expose counts, not per-question distributions, means, option breakdowns, or answer values. The raw-response list exposes response/file metadata and answerCount; actual values are available only through the dedicated /{responseId}/answers endpoint under RawResponsesRead.

Tenant Isolation

All Reports API responses are automatically scoped to the tenant associated with the API key. A key issued by Tenant A will never return surveys or responses belonging to Tenant B.

Notes

• Report data reflects rows available to the tenant at the moment of the request.
• Individual response rows require the explicit RawResponsesRead scope.
• The first three report reads are unpaged. Only raw responses accept page and pageSize (default 50, clamped to 100).