read_responses
Read response schema, counts, paginated rows, the export's column privacy catalog, exported survey JSON, or flow SVG for a survey. Rows require confirm: true and accept the Export tab's privacy presets and per-column Drop / Mask / Redact PII choices. The Export tab's named multi-filter views are browser-local and cannot be selected here: use review_decision for server-side review filtering, or page through rows and apply the same AND/OR predicates locally so pagination is not mistaken for the complete survey.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"survey_id": "<survey_id>"
},
"name": "read_responses"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max responses when include contains rows (default: 50, max: 200) | |
| cursor | No | Pagination cursor for rows (response ID from previous call) | |
| confirm | No | Required when include contains rows — ask the survey owner for explicit permission before fetching respondent answers, every call, not just once per session. | |
| include | No | What to return. rows requires confirm: true. columns lists every export column's key, sensitivity (identifier, free_text, demographic, device) and what each privacy preset does to it — no response data, so no confirm needed; use it to find the keys for dropped_column_keys / anonymized_question_ids. survey_json is the same versioned Domandata survey document the editor's Export → JSON writes (every block, question, option, and Flow setting, plus survey settings such as unfinished-response handling, the closed link, retention, and export privacy; API keys blanked; close date omitted), and imports back losslessly. | |
| survey_id | Yes | Survey UUID | |
| privacy_preset | No | Rows only. Starts from one of the Export tab's "Who is this file for?" presets: as_collected (Just Me), no_direct_identifiers (My Research Team), redacted (Reviewers or Collaborators), public_use (The Public), answers_only (Answers Only). The other privacy options can only add protection on top of it. public_use's rare-combination suppression is not applied here (rows are paginated) — use /api/v1/export or GitHub Sync for that. | |
| review_decision | No | Server-side filter for quality_review.decision. Named multi-filter views in the Export tab are stored in that browser, not on the survey, so they cannot be selected by MCP. For other predicates, page through rows and filter locally; do not treat one page as the full response set. | |
| coarsened_columns | No | Rows only. Broaden columns, keyed by column key: number ranges, month/year dates, 3-digit ZIP codes, or rare answers grouped. group_rare needs counts across all responses, so on paginated row reads those columns come back "withheld" — use /api/v1/export or GitHub Sync for it. | |
| use_saved_privacy | No | Rows only. Start from the survey's saved Export tab privacy choices (see include: ["columns"] → saved_privacy), so rows match what the Export tab would download; the other privacy options add protection on top. The team's export privacy minimum (columns → team_minimum) always applies to rows, with or without this. | |
| pii_redaction_mode | No | Rows only. Redacts email/phone/SSN-shaped text inside Text Response and Text Chat answers. unintentional leaves a question's own intended answer alone (e.g. an email-validated question); all redacts every match. Default off. | |
| dropped_column_keys | No | Rows only. Column keys left out entirely: a question id removes that question's answer; a "col:<header>" key removes that flow/JS variable or metadata field. Find keys with include: ["columns"]. | |
| redacted_question_ids | No | Rows only. Limits pii_redaction_mode to these free-text questions (the Export tab's per-column Redact PII). Omit to redact every Text Response / Text Chat answer when pii_redaction_mode is set. | |
| scan_names_and_places | No | Rows only. Also redacts people's names, places and organizations found in free-text answers. Default false. | |
| anonymized_question_ids | No | Rows only. Column keys whose values are masked: a question id replaces that answer with the literal string "anonymized"; a non-question "col:<header>" key (see include: ["columns"]) is removed from the raw row, since raw rows have no column to mask in place. | |
| pseudonymized_column_keys | No | Rows only. Column keys whose value is replaced by a coded ID (P-XXXXXXXXXXXX): the same original value gets the same code in every export of every survey in the team, so waves still link, and the code can't be reversed outside Domandata. For panel/respondent ID variables and identifying single-answer questions. | |
| include_identifying_questions | No | Rows only. false removes Text Response, signature, file upload, audio and chat answers entirely (default true, as typed). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |