Get survey
/v1/projects/{project_id}/surveys/{survey_id}Authorizations
Authorizationstringrequiredhttp
Path parameters
project_idstringrequiredAmplitude project identifier, backed by the canonical app ID.
12345pattern: ^[0-9]+$survey_idstringrequiredSurvey nudge identifier.
pattern: ^[0-9]+$Query parameters
include_unpublished_changesbooleanWhen true, return the latest draft (unpublished edits) when one exists. Default false returns the live published survey.
falseinclude_translationsbooleanWhen true, add localization (the project's default locale and other
locales) and each variant's translations and translation_status.
Read with include_unpublished_changes=true before writing
translations, so keys and latest_version match the draft. When
localization is disabled in the project settings, only
localization: {enabled: false} is added.
falseResponse
application/jsondataobjectrequiredShow child attributes
idstringrequiredNumeric nudge identifier.
pattern: ^[0-9]+$objectstringrequiredproject_idstringrequiredpattern: ^[0-9]+$typestringrequiredplatformstringrequiredTarget platform. Guides and surveys without an explicit platform are
returned as web.
webiosandroidreact-nativedesktopfluttertitlestringrequirednullabledescriptionstringnullableis_archivedbooleanrequiredpriorityintegerrequiredTrigger precedence (4 = urgent, 1 = low).
min: 1max: 4statusstringrequiredDerived rollout state. Read-only on API responses.
draftpublishedtestingscheduledscheduled-activescheduled-inactiveexperiment-runningexperiment-inactivearchivedstatus_descriptionstringrequiredkeystringrequiredFeature flag key that controls delivery. Matches the
[Guides-Surveys] Key property on SDK-tracked guide and survey events,
so use it to join events to this guide or survey.
nullablestart_atstringrequiredScheduled start of the live flag. null when no start is scheduled.
format: date-timenullableend_atstringrequiredScheduled end of the live flag. null when no end is scheduled.
format: date-timenullableurlstringrequiredAdmin URL for the guide or survey.
format: uripage_target_segmentsobject[]Pages where the guide or survey is eligible. Empty means every page.
urlstringrequiredPage URL or pattern for the URL match types.
matchTypestringrequiredsimpleexactpatterncontainsstartsWithendsWithregexdomSelectorisExcludebooleanrequiredWhen true, matching pages are excluded.
operatorstringHow this rule combines with the next one.
andorvaluestringCSS selector of an element that must be on the page. Required for
domSelector, which is web only.
tagsstring[]created_bystringnullablelast_modified_bystringnullablecreated_atstringrequiredformat: date-timenullableupdated_atstringrequiredformat: date-timenullablelatest_versionintegerrequiredMonotonic version for optimistic concurrency. Send the value from the latest GET on PATCH; a stale value returns 409.
temporarily_hide_page_target_segmentsobject[]Page rules that are saved but not currently applied.
urlstringrequiredPage URL or pattern for the URL match types.
matchTypestringrequiredsimpleexactpatterncontainsstartsWithendsWithregexdomSelectorisExcludebooleanrequiredWhen true, matching pages are excluded.
operatorstringHow this rule combines with the next one.
andorvaluestringCSS selector of an element that must be on the page. Required for
domSelector, which is web only.
hide_if_page_targeting_not_metbooleantrigger_configoneOfWhen the guide or survey appears. One trigger, or an array of triggers
where any match fires it. Nested keys keep their stored names (selector,
event, event_count, delay, filters). Don't send null: the dashboard can't open a
guide or survey without a trigger. Send {"type": "immediately"} to
show right away.
oneOf (object)oneOf[]typestringimmediatelynonesmart_delayrage_clickuser_confusionexit_intentelement_appearedelement_clickeddataobjectdelaynumberMilliseconds to wait after the trigger fires. Omit it rather than sending null.
min: 0sessionPropertyFiltersobject[][]Session property conditions. The inner arrays are AND groups, and the outer array ORs them.
selectorstringCSS selector of the element.
eventstringAnalytics event type that fires the trigger.
event_countintegerTimes the event must occur. Omitted means once.
min: 1filtersobject[]Event property conditions. Every condition must match.
subprop_keystringrequiredProperty name.
min length: 1subprop_opstringrequiredComparison operator, for example is, is not, or contains.
subprop_valuestring[]requiredValues to compare against.
subprop_typestringProperty type, for example event or user.
nullablegroup_typestringnullableunitstringsecondminutevaluenumberHow long to wait on the page before showing.
lifecycleobjectHow often the guide or survey may show again. periodCount is camelCase;
the other keys are snake_case. Send the whole object, not null.
stop_showing_if_completedbooleanrequiredstop_showing_if_dismissedbooleanrequiredsurvey_response_capobjectenabledbooleanvalueintegerStop after this many survey responses. Required when enabled is true.
min: 1cooldown_limitsobject[]requiredmaxintegerrequiredMaximum impressions in the period.
min: 1periodCountintegerHow many periods the limit covers. Omitted means 1.
min: 1periodstringrequireddayweekmonthyearsessioneven_distributionobjectenabledbooleanrequiredrecurrence_period_daysintegerrequiredDays over which impressions are spread evenly. Always required when even_distribution is sent.
min: 1dismissiblebooleansnoozablebooleansnoozable_on_all_stepsbooleansnooze_durationobjectHow long a snooze lasts.
intervalstringrequiredhourdayweekvaluenumberrequiredNumber of intervals.
snooze_labelstringnullabletemplate_sourcestringnullableshow_step_counterbooleanstep_counter_formatstringnullabletheme_idstringTheme applied to this guide or survey. null means the project's
default theme for the platform. Fetch it with the Themes API.
nullablepattern: ^[0-9]+$variantsobject[]idstringrequiredvariantstringrequiredVariant key within the nudge: lowercase letters, digits, - and _.
Keys must be unique. off is reserved, and control can't be given to
a new variant.
pattern: ^[a-z0-9_-]+$display_titlestringnullabledisplay_descriptionstringnullablesnooze_labelstringnullablemax length: 255done_labelstringnullablemax length: 255stepsobject[]idstringrequiredtitlestringnullablemax length: 255form_factoroneOfStep layout. type selects it. Every form factor also accepts
zIndexOverride (number or null) and textAnimation (typewriter).
Modal, popover, pin, tooltip, and card accept the step layout keys
layout, mediaPosition, contentAlignment, titleAlignment, and
footerLayout; banner and checklist accept a narrower set. Tooltips and cards can't be snoozed.
objecttypestringrequiredpositionstringWhere a modal or popover sits in the viewport.
top-lefttop-centertop-rightbottom-leftbottom-centerbottom-rightleft-centerright-centercentercanClickOutsideToClosebooleanfullWidthModalbooleanlayoutstringArrangement of media and text in the step.
classicverticalshowcasehorizontalmediaPositionstringMedia side for the horizontal layout.
leftrightcontentAlignmentstringstartcenterendtitleAlignmentstringstartcenterendfooterLayoutstringArrangement of the step's buttons.
classicsplitcenteredstackedcontentoneOf[]The step body: content blocks rendered top to bottom, below the step
title. meta keys are camelCase. Keep a block's existing uuid when
you edit it, because survey responses are keyed by it; a block sent
without one (or with null) is given one on save. To change one block,
send the step's whole content array back with that block edited. Send
[] for an empty step, not null.A step can have at most one markdown block, one image or one video
(not both), two buttons, ten survey questions, and ten survey_hidden
fields. Survey question blocks are only allowed in surveys, and only on
steps with the classic or vertical layout. A checklist item can have
at most one button. A snooze button needs the variant's snooze_label.
[{"uuid":"3f0c2a8e-5b1d-4c7a-9e2f-1a6b8d4c0e11","type":"markdown","meta":{"value":"Track any event in two clicks."}},{"uuid":"8d2e6f1a-7c3b-4e9d-a0f5-2b7c9e1d3a42","type":"button","meta":{"label":"Next","buttonType":"primary","action":{"type":"step_forward"}}}]uuidstringnullabletypestringrequiredmetaobjectrequiredvaluestringrequiredMarkdown text. Inline HTML is allowed and is sanitized on save.
alignmentstringstartcenterendtextAnimationstringcontent_v2oneOfBlock-builder layout: a tree of layout containers whose children
are containers or content blocks, including the step's title block.
Returned only on steps built in the block builder; when present, the
dashboard and SDK render this tree, not title and content.On update, only accepted on resources that already have a step with a
tree; a flat-only guide or survey can't be converted through the API.
On create, any step may take one, so a resource read with content_v2
can be copied. Block uuids must be unique within the step. Keep a block's
existing uuid when you edit it, because survey responses are keyed by
it; a block sent without one is given one on save. The saved tree is
normalized to the shape the block builder saves, and the step title is
taken from its title block. On a step with a tree, send title and
content only together with content_v2. Not supported on banner or
checklist steps or on mobile platforms. null switches the step back
to content.
objectnulltypestringchildrenoneOf[]uuidstringnullabletypestringsurvey_text is a multi-line answer; survey_text_short is a single line.
survey_textsurvey_text_shortmetaobjectvaluestringMarkdown text. Inline HTML is allowed and is sanitized on save.
alignmentstringstartcenterendtextAnimationstringsrcstringImage URL.
filenamestringsizestringaltTextstringstyleobjectscalestringradiusstringfitstringcovercontainheightstringactionobjectOptional link opened when the image is clicked. No other action type is allowed.
{"type":"link","value":"https://example.com/pricing","operation":"blank"}typestringrequiredCommon actions:
step_forward,step_back: go to the next or previous step.complete: finish the guide or survey.dismiss: close it.snooze: hide it for a while, with optionalinterval(hour,day,week) andvalue.go_to_step: jump to a step.valueis the 0-based position of the step in the variant'ssteps, not its id.link: open the URL invalue;operationisself(same tab),blank(new tab) orrouter.nudge: start another guide or survey.valueis its numeric id, andproductTypeisguideorsurvey.no_action: no action of its own. The button still advances: to the next step, or on the last step it finishes the guide or survey. The dashboard's survey templates use it for the submit button. It does not keep the user on the step;stay_on_stepdoes.
Buttons built in the dashboard can also use stay_on_step,click (value is a CSS selector), callback, app_review,open_resource_center, open_ai_assistant, open_chat, document,video, and use_conditional_logic. Send those back unchanged.
valuestringURL to open.
operationstringselfblankroutertypestringnps is a 0–10 scale and takes options: 10.
starsnumbersemojisnpslabelstringbuttonTypestringprimarysecondarysnoozegrowbooleanStretch the button to fill the footer row.
widthstringCSS width, for example 100%.
actionsobjectOptional action sequence the dashboard writes for buttons with side
effects: {type: "action_sequence", navigation: <action>, effects: [<action>]}.
When present, the SDK runs it instead of action, so update both or
neither.
promptstringPlaceholder shown in the empty answer field. Required; send "" for none.
ariaLabelstringprefillobjectsurvey_text_short only.
enabledbooleanrequireduserPropertystringrequiredUser property whose value fills the answer.
validationobjectrequiredobjectvaluebooleanrequiredmessagestringError shown when a required question is left empty. Required when value is true.
nullableoptionsarray or integerNumber of choices on the scale. Allowed values depend on type:
stars 3 or 5, numbers 3, 5, 7 or 10, emojis 2, 3 or 5, and
nps 10.
listTypestringsinglemultipledisplayTypestringlistdropdowngridisOrderRandombooleanotherOptionobjectenabledbooleanrequiredlabelstringrequiredplaceholderLabelstringrequiredemojisstring[]Exactly one emoji per option. Required when type is emojis.
lowerLabelstringupperLabelstringsourceoneOfobjecttypestringrequiredvaluestringrequiredThe value to record.
formatstringnumericverboseidstringContainer id, unique within the step.
directionstringrowcolumnjustifystringstartcenterendspace-betweenspace-aroundalignstringstartcenterendgapstringCSS length, for example 8px.
paddingstringmarginstringpinnedbooleanwrapbooleanoverflowstringautohiddenminHeightstringwidthstringsort_keyintegernullabletranslationsobjectStored translations, locale to translation key to text. Returned with
include_translations=true and on updates that send translations.
translation_statusobjectWhat is left to translate. sources lists every translatable key with its
current default-locale text. Per locale, missing keys have no
translation and outdated keys were translated from text that has since
changed.
sourcesobjectrequiredlocalesobjectrequiredexperiment_variantsobject[]Read-only experiment variant keys when the nudge is experiment-backed.
keystringrequirednamestringnullabledescriptionstringnullablepayloadunknownOptional JSON payload associated with the experiment variant.
flag_configoneOfThe Experiment feature flag that delivers this nudge, in the same
shape as the Feature Flags API. Includes audience targeting
(target_segments) and rollout. With
include_unpublished_changes=true, draft rollout and targeting
settings are applied over the live flag.
objectnullidstringproject_idstringpattern: ^[0-9]+$keystringnamestringdescriptionstringnullabledeploymentsstring[]Deployment IDs associated with this flag. Managed via the create/update deployment fields, not set directly on this field.
enabledbooleanevaluation_modestringlocalremotevariantsobject[]keystringrequiredStable variant key. The value off is reserved.
pattern: ^[A-Za-z0-9_-]+$namestringnullabledescriptionstringnullablepayloadunknownOptional JSON payload returned by evaluation.
bucketing_keystringBucketing key used for assignment. Never null in responses; defaults to amplitude_id when not explicitly set.
bucketing_saltstringnullablebucketing_unitstringnullablerollout_percentageintegermin: 0max: 100rollout_weightsobjectVariant-keyed rollout weights. Values may be normalized to sum to 100 (percentages) or expressed as unnormalized relative weights (for example { "control": 1, "treatment": 1 } for an even split). Weights are non-negative and may be fractional.
target_segmentsobject[]namestringnullableconditionsobject[]requiredgroup_typestringnullablepropstringrequiredProperty name or cohort identifier being targeted.
min length: 1prop_typestringNamespace of the targeted property, for example user, event, or group. Omitted for conditions that target a cohort rather than a property.
nullableopstringrequiredTargeting operator applied to the property values.
isis notcontainsdoes not containlessless or equalgreatergreater or equalset isset is notset containsset does not containglob matchglob does not matchtypestringrequiredCondition type, for example property or cohort.
valuesstring[]requiredAt least one value to match against. Conditions with no values are rejected.
percentageintegerSegment rollout percentage.
nullablemin: 0max: 100rollout_weightsobjectVariant-keyed rollout weights. Values may be normalized to sum to 100 (percentages) or expressed as unnormalized relative weights (for example { "control": 1, "treatment": 1 } for an even split). Weights are non-negative and may be fractional.
bucketing_keystringnullabletestersobject[]variant_keystringrequiredvaluesstring[]requiredUser IDs, device IDs, or cohort identifiers included in this variant. At most 2000 entries per variant (the limit is 10 when the entries are cohort identifiers).
ownersstring[]tagsstring[]created_bystringnullablelast_modified_bystringnullablecreated_atstringformat: date-timenullableupdated_atstringformat: date-timenullableparent_dependenciesobjectoperatorstringrequiredallanyflagsobject[]requiredflag_idstringrequiredallowed_variantsstring[]linksobject[]urlstringrequiredformat: urititlestringrequiredversionintegerServer-managed config version used for optimistic concurrency.
archivedbooleanWhether the resource is archived. Set via the archive (DELETE) operation.
urlstringformat: urinullableobjectstringResource-type discriminator. Always feature_flag.
localizationobjectThe project's localization settings. locales are the languages other
than default_locale that translations can be written for. Configure them
in project settings. When localization is disabled, only enabled: false
is returned and variants carry no translations or translation_status.
enabledbooleanrequireddefault_localestringlocalesstring[]Was this helpful?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.