Get guide

get/v1/projects/{project_id}/guides/{guide_id}

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345
Constraints:pattern: ^[0-9]+$
guide_idstringrequired

Guide (tour nudge) identifier.

Constraints:pattern: ^[0-9]+$

Query parameters

include_unpublished_changesboolean

When true, return the latest draft (unpublished edits) when one exists. Default false returns the live published guide.

Default:false
include_translationsboolean

When 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.

Default:false

Response

application/json
200· Successful response.
dataobjectrequired
Show child attributes
idstringrequired

Numeric nudge identifier.

Constraints:pattern: ^[0-9]+$
objectstringrequired
project_idstringrequired
Constraints:pattern: ^[0-9]+$
typestringrequired
platformstringrequired

Target platform. Guides and surveys without an explicit platform are returned as web.

Allowed values:webiosandroidreact-nativedesktopflutter
titlestringrequired
Constraints:nullable
descriptionstring
Constraints:nullable
is_archivedbooleanrequired
priorityintegerrequired

Trigger precedence (4 = urgent, 1 = low).

Constraints:min: 1max: 4
statusstringrequired

Derived rollout state. Read-only on API responses.

Allowed values:draftpublishedtestingscheduledscheduled-activescheduled-inactiveexperiment-runningexperiment-inactivearchived
status_descriptionstringrequired
keystringrequired

Feature 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.

Constraints:nullable
start_atstringrequired

Scheduled start of the live flag. null when no start is scheduled.

Constraints:format: date-timenullable
end_atstringrequired

Scheduled end of the live flag. null when no end is scheduled.

Constraints:format: date-timenullable
urlstringrequired

Admin URL for the guide or survey.

Constraints:format: uri
page_target_segmentsobject[]

Pages where the guide or survey is eligible. Empty means every page.

urlstringrequired

Page URL or pattern for the URL match types.

matchTypestringrequired
Allowed values:simpleexactpatterncontainsstartsWithendsWithregexdomSelector
isExcludebooleanrequired

When true, matching pages are excluded.

operatorstring

How this rule combines with the next one.

Allowed values:andor
valuestring

CSS selector of an element that must be on the page. Required for domSelector, which is web only.

tagsstring[]
created_bystring
Constraints:nullable
last_modified_bystring
Constraints:nullable
created_atstringrequired
Constraints:format: date-timenullable
updated_atstringrequired
Constraints:format: date-timenullable
latest_versionintegerrequired

Monotonic 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.

urlstringrequired

Page URL or pattern for the URL match types.

matchTypestringrequired
Allowed values:simpleexactpatterncontainsstartsWithendsWithregexdomSelector
isExcludebooleanrequired

When true, matching pages are excluded.

operatorstring

How this rule combines with the next one.

Allowed values:andor
valuestring

CSS selector of an element that must be on the page. Required for domSelector, which is web only.

hide_if_page_targeting_not_metboolean
trigger_configoneOf

When 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.

Constraints:oneOf (object)oneOf[]
typestring
Allowed values:immediatelynonesmart_delayrage_clickuser_confusionexit_intentelement_appearedelement_clicked
dataobject
delaynumber

Milliseconds to wait after the trigger fires. Omit it rather than sending null.

Constraints:min: 0
sessionPropertyFiltersobject[][]

Session property conditions. The inner arrays are AND groups, and the outer array ORs them.

selectorstring

CSS selector of the element.

eventstring

Analytics event type that fires the trigger.

event_countinteger

Times the event must occur. Omitted means once.

Constraints:min: 1
filtersobject[]

Event property conditions. Every condition must match.

subprop_keystringrequired

Property name.

Constraints:min length: 1
subprop_opstringrequired

Comparison operator, for example is, is not, or contains.

subprop_valuestring[]required

Values to compare against.

subprop_typestring

Property type, for example event or user.

Constraints:nullable
group_typestring
Constraints:nullable
unitstring
Allowed values:secondminute
valuenumber

How long to wait on the page before showing.

lifecycleobject

How 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_completedbooleanrequired
stop_showing_if_dismissedbooleanrequired
survey_response_capobject
enabledboolean
valueinteger

Stop after this many survey responses. Required when enabled is true.

Constraints:min: 1
cooldown_limitsobject[]required
maxintegerrequired

Maximum impressions in the period.

Constraints:min: 1
periodCountinteger

How many periods the limit covers. Omitted means 1.

Constraints:min: 1
periodstringrequired
Allowed values:dayweekmonthyearsession
even_distributionobject
enabledbooleanrequired
recurrence_period_daysintegerrequired

Days over which impressions are spread evenly. Always required when even_distribution is sent.

Constraints:min: 1
dismissibleboolean
snoozableboolean
snoozable_on_all_stepsboolean
snooze_durationobject

How long a snooze lasts.

intervalstringrequired
Allowed values:hourdayweek
valuenumberrequired

Number of intervals.

snooze_labelstring
Constraints:nullable
template_sourcestring
Constraints:nullable
show_step_counterboolean
step_counter_formatstring
Constraints:nullable
theme_idstring

Theme applied to this guide or survey. null means the project's default theme for the platform. Fetch it with the Themes API.

Constraints:nullablepattern: ^[0-9]+$
variantsobject[]
idstringrequired
variantstringrequired

Variant 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.

Constraints:pattern: ^[a-z0-9_-]+$
display_titlestring
Constraints:nullable
display_descriptionstring
Constraints:nullable
snooze_labelstring
Constraints:nullablemax length: 255
done_labelstring
Constraints:nullablemax length: 255
stepsobject[]
idstringrequired
titlestring
Constraints:nullablemax length: 255
form_factoroneOf

Step 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.

Constraints:object
One of 7 shapes:
typestringrequired
positionstring

Where a modal or popover sits in the viewport.

Allowed values:top-lefttop-centertop-rightbottom-leftbottom-centerbottom-rightleft-centerright-centercenter
canClickOutsideToCloseboolean
fullWidthModalboolean
layoutstring

Arrangement of media and text in the step.

Allowed values:classicverticalshowcasehorizontal
mediaPositionstring

Media side for the horizontal layout.

Allowed values:leftright
contentAlignmentstring
Allowed values:startcenterend
titleAlignmentstring
Allowed values:startcenterend
footerLayoutstring

Arrangement of the step's buttons.

Allowed values:classicsplitcenteredstacked
contentoneOf[]

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.

Example:[{"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"}}}]
One of 8 shapes:
uuidstring
Constraints:nullable
typestringrequired
metaobjectrequired
valuestringrequired

Markdown text. Inline HTML is allowed and is sanitized on save.

alignmentstring
Allowed values:startcenterend
textAnimationstring
content_v2oneOf

Block-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.

Constraints:objectnull
typestring
childrenoneOf[]
uuidstring
Constraints:nullable
typestring

survey_text is a multi-line answer; survey_text_short is a single line.

Allowed values:survey_textsurvey_text_short
metaobject
valuestring

Markdown text. Inline HTML is allowed and is sanitized on save.

alignmentstring
Allowed values:startcenterend
textAnimationstring
srcstring

Image URL.

filenamestring
sizestring
altTextstring
styleobject
scalestring
radiusstring
fitstring
Allowed values:covercontain
heightstring
actionobject

Optional link opened when the image is clicked. No other action type is allowed.

Example:{"type":"link","value":"https://example.com/pricing","operation":"blank"}
typestringrequired

Common 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 optional interval (hour, day, week) and value.
  • go_to_step: jump to a step. value is the 0-based position of the step in the variant's steps, not its id.
  • link: open the URL in value; operation is self (same tab), blank (new tab) or router.
  • nudge: start another guide or survey. value is its numeric id, and productType is guide or survey.
  • 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_step does.

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.

valuestring

URL to open.

operationstring
Allowed values:selfblankrouter
typestring

nps is a 0–10 scale and takes options: 10.

Allowed values:starsnumbersemojisnps
labelstring
buttonTypestring
Allowed values:primarysecondarysnooze
growboolean

Stretch the button to fill the footer row.

widthstring

CSS width, for example 100%.

actionsobject

Optional 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.

promptstring

Placeholder shown in the empty answer field. Required; send "" for none.

ariaLabelstring
prefillobject

survey_text_short only.

enabledbooleanrequired
userPropertystringrequired

User property whose value fills the answer.

validationobject
requiredobject
valuebooleanrequired
messagestring

Error shown when a required question is left empty. Required when value is true.

Constraints:nullable
optionsarray or integer

Number 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.

listTypestring
Allowed values:singlemultiple
displayTypestring
Allowed values:listdropdowngrid
isOrderRandomboolean
otherOptionobject
enabledbooleanrequired
labelstringrequired
placeholderLabelstringrequired
emojisstring[]

Exactly one emoji per option. Required when type is emojis.

lowerLabelstring
upperLabelstring
sourceoneOf
Constraints:object
One of 2 shapes:
typestringrequired
valuestringrequired

The value to record.

formatstring
Allowed values:numericverbose
idstring

Container id, unique within the step.

directionstring
Allowed values:rowcolumn
justifystring
Allowed values:startcenterendspace-betweenspace-around
alignstring
Allowed values:startcenterend
gapstring

CSS length, for example 8px.

paddingstring
marginstring
pinnedboolean
wrapboolean
overflowstring
Allowed values:autohidden
minHeightstring
widthstring
sort_keyinteger
Constraints:nullable
translationsobject

Stored translations, locale to translation key to text. Returned with include_translations=true and on updates that send translations.

translation_statusobject

What 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.

sourcesobjectrequired
localesobjectrequired
experiment_variantsobject[]

Read-only experiment variant keys when the nudge is experiment-backed.

keystringrequired
namestring
Constraints:nullable
descriptionstring
Constraints:nullable
payloadunknown

Optional JSON payload associated with the experiment variant.

flag_configoneOf

The 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.

Constraints:objectnull
idstring
project_idstring
Constraints:pattern: ^[0-9]+$
keystring
namestring
descriptionstring
Constraints:nullable
deploymentsstring[]

Deployment IDs associated with this flag. Managed via the create/update deployment fields, not set directly on this field.

enabledboolean
evaluation_modestring
Allowed values:localremote
variantsobject[]
keystringrequired

Stable variant key. The value off is reserved.

Constraints:pattern: ^[A-Za-z0-9_-]+$
namestring
Constraints:nullable
descriptionstring
Constraints:nullable
payloadunknown

Optional JSON payload returned by evaluation.

bucketing_keystring

Bucketing key used for assignment. Never null in responses; defaults to amplitude_id when not explicitly set.

bucketing_saltstring
Constraints:nullable
bucketing_unitstring
Constraints:nullable
rollout_percentageinteger
Constraints:min: 0max: 100
rollout_weightsobject

Variant-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[]
namestring
Constraints:nullable
conditionsobject[]required
group_typestring
Constraints:nullable
propstringrequired

Property name or cohort identifier being targeted.

Constraints:min length: 1
prop_typestring

Namespace of the targeted property, for example user, event, or group. Omitted for conditions that target a cohort rather than a property.

Constraints:nullable
opstringrequired

Targeting operator applied to the property values.

Allowed values:isis notcontainsdoes not containlessless or equalgreatergreater or equalset isset is notset containsset does not containglob matchglob does not match
typestringrequired

Condition type, for example property or cohort.

valuesstring[]required

At least one value to match against. Conditions with no values are rejected.

percentageinteger

Segment rollout percentage.

Constraints:nullablemin: 0max: 100
rollout_weightsobject

Variant-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_keystring
Constraints:nullable
testersobject[]
variant_keystringrequired
valuesstring[]required

User 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_bystring
Constraints:nullable
last_modified_bystring
Constraints:nullable
created_atstring
Constraints:format: date-timenullable
updated_atstring
Constraints:format: date-timenullable
parent_dependenciesobject
operatorstringrequired
Allowed values:allany
flagsobject[]required
flag_idstringrequired
allowed_variantsstring[]
linksobject[]
urlstringrequired
Constraints:format: uri
titlestringrequired
versioninteger

Server-managed config version used for optimistic concurrency.

archivedboolean

Whether the resource is archived. Set via the archive (DELETE) operation.

urlstring
Constraints:format: urinullable
objectstring

Resource-type discriminator. Always feature_flag.

localizationobject

The 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.

enabledbooleanrequired
default_localestring
localesstring[]

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.