Responses and versions
Respondents use /{workspaceSlug}/{projectSlug}/{surveySlug}. The public page loads the latest published version, and its footer shows that version. Saving a draft never changes a publication. Publishing creates an immutable version for new sessions; existing sessions retain their original version.
Collect responses through the hosted survey or generated embed. This guide covers authenticated access to results, exports and reports.
Published versions remain separate in results. Tracked links identify the source used to reach the survey; they do not verify a person’s identity.
Read the complete dataset
GET /api/v1/surveys/{surveyId}/results requires workspace/project access and a browser session or responses:read token. It returns full-cohort analysis, status totals, immutable versions, a bounded responses page, snapshot metadata and nextCursor. It no longer limits analytical input to the latest 100 sessions.
GET /api/v1/surveys/SURVEY_ID/results?version=1&outcome=complete&limit=50
GET /api/v1/surveys/SURVEY_ID/results?snapshot=SNAPSHOT_ID&after=NEXT_CURSOR&limit=50
Use the returned cursor unchanged. Pages are ordered by session UUID, not recency. limit is 1–100 (default 50). A null cursor ends the dataset. Each page rechecks current authorization; possessing a snapshot ID never grants access. Snapshots belong to the specific user or token that created them.
First-request filters: version; outcome (complete, screened_out, partial, in_progress); link (tracked link UUID or direct); and ISO datetime from (inclusive) / to (exclusive), using the latest accepted event's server time. Filters apply after selecting each session's latest accepted event. Omitted filters select all sessions. Versions are always analyzed separately. Subsequent pages pass the snapshot and cursor, without cohort filters. The dashboard shows the active cohort and capture time.
Snapshot consistency and refresh
A results snapshot freezes the version graphs and latest accepted answers visible when it is captured. Later answers cannot change the pinned event or totals. Click Refresh results or omit snapshot to capture new answers.
These are temporary browsing caches, not saved report runs. Snapshots expire after 24 hours; only the ten newest per actor/survey are kept. An expired or evicted snapshot returns 404 with a refresh instruction. Saved reports described below are independent of this cache. Owner research deletion is described in the deletion guide.
Denominators and interpretation
- Saved starts: sessions with accepted events, not page visits. Completion rate is completed / saved starts in the selected cohort; screen-outs remain a separate outcome.
- Eligible: all saved sessions in this version and cohort. Reached: answered questions plus the current unanswered question on the validated path. This is derived from saved state, not a claim that the browser visibly displayed it.
- Answered: valid non-null, non-empty values. Skipped: explicit null. Empty: accepted empty string or empty selection. Pending: reached but no saved answer. Not reached: branch-excluded or later questions not yet reached; the API does not guess counterfactual eligibility.
- Choice shares divide each option's respondent count by answered respondents. Multi-select shares may sum above 100%; selections and answered respondents are separate counts. Ratings show scale labels, distribution and mean with the answered base. Numeric inputs have a mean, not invented category distributions.
- Empty cohorts have no findings or calculated rates (
null), and appear as No matching responses. Text answers remain individual text; no AI analysis, representativeness claim or cross-version merging is performed.
The console provides Overview, question denominator/distribution tables and Load more responses. The same recipe and suppression service feeds private charts and aggregate CSV. Individual records remain visible to authorized raw-response readers; these are not anonymous reports.
Private reports and complete exports
The Responses page offers charts and downloads for the complete selected dataset, independent of the visible response page. Rating/choice charts use answered respondents; multi-select shares can exceed 100%. Text has no automatic interpretation. CSAT uses ratings 4 or 5 divided by non-empty answered values on the original 1–5 scale; editing that scale makes its recipe unavailable. All versions remain separate.
Endpoint suffix after /api/v1/surveys/{surveyId} | Method | Purpose |
|---|---|---|
/research-brief | GET / PUT | Read/update the optional project-wide research brief. PUT accepts { "revision": 0, "brief": { "objective": "Choose next topic" } }. Fields: objective, population, recruitment, comparisons, limitations (each ≤4,000 characters). Stale revisions return 409. |
/analysis-runs | POST | Save { "snapshotId": "UUID", "title": "Report title" } with required Idempotency-Key. Returns the saved run (201). |
/analysis-runs | GET | Up to 50 runs, descending UUID order. Follow nextCursor as after until null. |
/analysis-runs/{runId} | GET | Read the frozen run, selected versions, brief, config and protected report results. |
/exports/responses.csv | GET | Every selected session/question, including explicit answer state. |
/exports/codebook.csv | GET | Versioned question IDs, wording, options and rating labels. |
/exports/aggregates.csv | GET | The same protected counts, bases and recipe measures shown in charts. |
CSV requests require exactly one query parameter: snapshot=UUID (unexpired, actor-owned browsing snapshot) or run=UUID (saved report). Raw CSV is long-form: one row per session/question, with stable IDs and answered, skipped, empty, pending, or not_reached. Answers are JSON within quoted CSV cells. Formula-leading cells are escaped for spreadsheet safety; a leading apostrophe is an export safety marker, not a changed source answer.
Reads/export require responses:read. Creating runs or updating briefs additionally requires reports:write and an editor role; * covers both, surveys:* does not. Browser writes use the existing session, Origin and CSRF header. Every request rechecks workspace/project access. Saved reports can be read by any authorized response reader in that scope, even if another member created them.
Reuse the same creation key (16–128 letters/digits/hyphens/underscores) and snapshot/title on retry. Different parameters with that key return 409. A new intention needs a new key. ready, empty, and failed are explicit stored states; failed runs cannot export. Refresh and save a new report after a failure.
A saved report preserves the selected data, survey versions, filters and project brief. Later responses or edits do not change it. Deleting its source research makes the affected report unavailable rather than silently recalculating its findings.
Employee reports and disclosure
Employee Satisfaction is available with base-five protection. If any positive outcome, question denominator or option cell is below five, the entire version's analytical tables, totals, means and recipes are withheld. This conservative complementary suppression prevents reconstructing a hidden cell from another table in that report. Link aggregates similarly withhold all rows when one has a small cell. Suppression is shared by JSON, charts, saved runs and aggregate exports.
Public employee intros and previews explain that authorized organization members can read individual answers and written text, and that the survey is not anonymous. Authors cannot remove the server-enforced disclosure by editing the draft. Raw responses/CSV remain available with responses:read; aggregate suppression is not a privacy barrier against someone already permitted to inspect raw records, nor a differential-privacy guarantee across arbitrary query combinations. No public report link or AI interpretation is provided.
Deleting research
Owners can delete response data and saved reports from the survey Responses page or project page. Collection closes, old publications cannot resume, and only the owner can publish a new version to collect again. Consumed capacity is preserved. See deletion scope and confirmation.