--- title: "Retrieve a survey" method: GET path: "/api/v3/surveys/{surveyId}" tags: ["V3 Surveys"] --- # Retrieve a survey `GET /api/v3/surveys/{surveyId}` Returns the public v3 survey management resource for one survey. By default, translatable fields are returned as stable multilingual maps keyed by the language codes emitted in `languages[].code`. Use `lang` to filter those maps to one or more requested language selectors. ## Path parameters - `surveyId` string, cuid2, required ## Query parameters - `lang` string[] ## Response `200` Survey retrieved successfully - object - `data` SurveyResource, required - `id` string, required - `workspaceId` string, required - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `name` string, required - `type` 'link' | 'app' | 'website' | 'web', required - `status` 'draft' | 'inProgress' | 'paused' | 'completed', required - `metadata` object, nullable, required - `defaultLanguage` string, required — Emitted language code/tag for the survey default language. The internal `default` translation key is never exposed. - `languages` SurveyLanguage[], required - `code` string, required — Server-emitted survey language code/tag used as the translatable map key. - `alias` string, nullable — Optional configured alias accepted by `?lang` for compatibility and agent discovery. - `default` boolean, required — Whether this is the default authoring language. - `enabled` boolean, required — Whether this language is enabled for respondent-facing delivery. - `welcomeCard` SurveyWelcomeCard, required — Optional card shown before the first survey block. - `enabled` boolean, required - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `fileUrl` string - `videoUrl` string - `timeToFinish` boolean - `showResponseCount` boolean - `blocks` SurveyBlock[], required - `id` string, cuid2, required — Stable block id. - `name` string, required - `elements` SurveyElement[], required - `id` string, required — Stable element id. Avoid spaces and reserved ids. - `type` 'openText' | 'multipleChoiceSingle' | 'multipleChoiceMulti' | 'nps' | 'rating' | 'csat' | 'ces' | 'consent' | 'pictureSelection' | 'cta' | 'date' | 'fileUpload' | 'cal' | 'matrix' | 'address' | 'ranking' | 'contactInfo', required - `headline` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `required` boolean, required - `imageUrl` string - `videoUrl` string - `isDraft` boolean — Draft marker used by the editor and future update rules. - `placeholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `longAnswer` boolean — `openText` only. - `inputType` 'text' | 'email' | 'url' | 'number' | 'phone' — `openText` only. - `charLimit` object — `openText` character limit configuration. - `enabled` boolean - `min` number - `max` number - `choices` union[] — Choice list for multiple choice, ranking, and picture selection elements. - union - SurveyChoice - … - SurveyPictureChoice - … - `shuffleOption` 'none' | 'all' | 'exceptLast' | 'reverseOrderOccasionally' | 'reverseOrderExceptLast' - `displayType` 'list' | 'dropdown' — Multiple choice display style. - `otherOptionPlaceholder` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `lowerLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `upperLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `isColorCodingEnabled` boolean - `scale` 'number' | 'smiley' | 'star' — Rating, CSAT, CES, or NPS scale display. - `range` 3 | 4 | 5 | 6 | 7 | 10 — Rating range. CSAT is always 5; CES is 5 or 7. - `label` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `allowMulti` boolean — `pictureSelection` only. - `buttonExternal` boolean — `cta` only. - `buttonUrl` string — `cta` only. - `ctaButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `html` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `format` 'M-d-y' | 'd-M-y' | 'y-M-d' — `date` only. - `allowMultipleFiles` boolean — `fileUpload` only. - `maxSizeInMB` number — `fileUpload` only. - `allowedFileExtensions` string[] — `fileUpload` only. - `calUserName` string — `cal` only. - `calHost` string — `cal` only. - `rows` SurveyChoice[] — Matrix rows. - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `columns` SurveyChoice[] — Matrix columns. - `id` string, required — Stable choice id. - `label` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `addressLine1` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `addressLine2` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `city` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `state` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `zip` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `country` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `firstName` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `lastName` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `email` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `phone` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `company` SurveyToggleInputConfig — Field config for address and contact info elements. - `show` boolean, required - `required` boolean, required - `placeholder` TranslatableText, required — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `validation` SurveyValidation — Optional element-level validation rules. - `logic` 'and' | 'or' - `rules` SurveyValidationRule[], required - `id` string, required - `type` 'minLength' | 'maxLength' | 'pattern' | 'email' | 'url' | 'phone' | 'equals' | 'doesNotEqual' | 'contains' | 'doesNotContain' | 'minValue' | 'maxValue' | 'isGreaterThan' | 'isLessThan' | 'minSelections' | 'maxSelections' | 'minRanked' | 'rankAll' | 'minRowsAnswered' | 'answerAllRows' | 'isLaterThan' | 'isEarlierThan' | 'isBetween' | 'isNotBetween' | 'fileExtensionIs' | 'fileExtensionIsNot', required - `params` object, required - `field` 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'zip' | 'country' | 'firstName' | 'lastName' | 'email' | 'phone' | 'company' - `logic` SurveyBlockLogic[] - `id` string, cuid2, required - `conditions` SurveyConditionGroup, required - `id` string, cuid2, required - `connector` 'and' | 'or', required - `conditions` union[], required - union - … - `actions` SurveyLogicAction[], required - union — Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id, `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id or ending id. - SurveyCalculateAction — Updates a survey variable when the logic rule matches. - … - SurveyRequireAnswerAction — Requires an element/question to be answered before continuing. - … - SurveyJumpToBlockAction — Jumps to another block or ending when the logic rule matches. - … - `logicFallback` string, cuid2 — Block or ending id used when no logic condition matches. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `backButtonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `endings` SurveyEnding[], required - `id` string, cuid2, required — Stable ending id. `jumpToBlock.target` may point to this id. - `type` 'endScreen' | 'redirectToUrl', required - `headline` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `subheader` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLabel` TranslatableText — Multilingual text map keyed by the emitted `languages[].code` values for this survey. - `buttonLink` string - `imageUrl` string - `videoUrl` string - `url` string — Redirect URL for `redirectToUrl` endings. - `label` string — Optional internal label for redirect endings. - `hiddenFields` SurveyHiddenFields, required — Hidden fields, sometimes called embedded data in other survey products. Field ids are stable public identifiers and may be referenced by logic, recall, quotas, integrations, and response data. Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids. - `enabled` boolean, required - `fieldIds` string[] - `variables` SurveyVariable[], required - union — Survey variable. Variable ids are stable references used by logic and calculation actions. Variable names are human-readable labels and must be unique within the survey. - SurveyNumberVariable — Number variable. Used by `calculate` logic actions with numeric operators such as `add`, `subtract`, `multiply`, `divide`, or `assign`. - `id` string, cuid2, required — Stable variable id referenced from logic. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'number', required - `value` number, required — Default numeric value. - SurveyTextVariable — Text variable. Used by `calculate` logic actions with text operators such as `assign` or `concat`. - `id` string, cuid2, required — Stable variable id referenced from logic. - `name` string, required — Unique variable name. Lowercase letters, numbers, and underscores only. - `type` 'text', required - `value` string, required — Default text value. ## Other responses - `400` — Invalid survey id, unsupported query parameter, unknown language, or unsupported legacy survey shape - `401` — Not authenticated (no valid session or API key) - `403` — Forbidden — no access, or survey does not exist (404 not used; avoids existence leak) - `429` — Rate limit exceeded - `500` — Internal Server Error ## Changes - **2026-05-28** `23ec9fd15a38` — 1 info - endpoint added - **2026-03-20** `9fa9931e1a70` — 1 breaking - api path removed without deprecation [Change history](https://skmtc.dev/formbricks/apis/formbricks-api-v3/changes/api/v3/surveys/:surveyId/get.md) --- [API](https://skmtc.dev/formbricks/apis/formbricks-api-v3.md) · [All operations](https://skmtc.dev/formbricks/apis/formbricks-api-v3/llms.txt) · [OpenAPI document](https://skmtc.dev/formbricks/apis/formbricks-api-v3/revisions/23ec9fd15a38?raw)