---
title: amp surveys
description: "Reference for amp surveys list, get, create, update, and archive, which manage draft in-app surveys."
product: general
lang: en
last_updated: 2026-11-18
token_estimate: 1844
---
# amp surveys

`amp surveys` manages in-app surveys. Read commands require `surveys:read`; create, update, and archive require `surveys:write`. Publish and schedule surveys in Amplitude.

## `amp surveys list`

Returns surveys in the project. Results use the standard Developer API list envelope with cursor pagination (`cursor`, `limit`).

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

Full-text search (`q`) and custom sort orders are not supported yet.

```bash
amp surveys list --project <project_id> --limit 10
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--cursor` | string | No | Opaque cursor from `pagination.next_cursor` on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 `pagination_not_supported`. Alias: `--next-cursor`. |
| `--limit` | integer | No | Number of items to return. Defaults to 50, max 200. |
| `--platform` | string | No |  |
| `--created-after` | string | No |  |
| `--created-before` | string | No |  |
| `--created-by` | string | No | Filter by creator email or login id (exact match). |
| `--include-archived` | boolean | No |  |

Requires the `surveys:read` scope.

## `amp surveys get`

Get survey.

```bash
amp surveys get --project <project_id> --survey <survey_id> --include-unpublished-changes
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--survey` | string | Yes | Survey nudge identifier. Alias: `--survey-id`. |
| `--include-unpublished-changes` | boolean | No | When true, return the latest draft (unpublished edits) when one exists. Default false returns the live published survey. |

Requires the `surveys:read` scope.

## `amp surveys create`

Creates an unpublished draft survey. Publish, schedule, and test instrumentation are not available via API in v1. At most one content variant is accepted on create; the `control` key is reserved.

```bash
amp surveys create --project <project_id> --title "NPS survey"
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--title` | string | Yes |  |
| `--description` | string | No |  |
| `--platform` | string: `web`, `ios`, `android`, `react-native`, `desktop`, `flutter` | No | Target platform. Guides and surveys without an explicit platform are returned as `web`. |
| `--priority` | integer | No |  |
| `--variants` | array | No | JSON array, or a comma-separated list for strings. |

Requires the `surveys:write` scope.

## `amp surveys update`

Updates metadata, targeting, and content variants. For published surveys, changes apply to a draft until publish in the UI. `latest_version` is required and must match the current draft, otherwise the update returns `409`. The check runs before the write rather than atomically with it, so it reduces but does not fully prevent lost updates from concurrent writers. Publish, schedule, and test instrumentation are not available via API in v1. Status fields on the response are derived read-only. When `variants` is sent, it must list every existing variant by `id` with its unchanged `variant` key; steps within a variant can be added, edited, reordered, or removed. `tags` is not writable in v1 and returns `400`.

```bash
amp surveys update --project <project_id> --survey <survey_id> --latest-version <version> --title "NPS survey v2"
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--survey` | string | Yes | Survey nudge identifier. Alias: `--survey-id`. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |
| `--title` | string | No |  |
| `--description` | string | No |  |
| `--platform` | string: `web`, `ios`, `android`, `react-native`, `desktop`, `flutter` | No | Target platform. Guides and surveys without an explicit platform are returned as `web`. |
| `--priority` | integer | No |  |
| `--page-target-segments` | array | No | Pages where the survey is eligible. Empty means every page. Each item uses camelCase keys. JSON array, or a comma-separated list for strings. |
| `--temporarily-hide-page-target-segments` | array | No | Page rules that are saved but not currently applied. JSON array, or a comma-separated list for strings. |
| `--hide-if-page-targeting-not-met` | boolean | No |  |
| `--trigger-config` | object | No | 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`). Optional `filters` and `sessionPropertyFilters` are accepted and passed through. |
| `--lifecycle` | object | No | How often the guide or survey may show again. `periodCount` is camelCase; the other keys are snake\_case. |
| `--dismissible` | boolean | No |  |
| `--snoozable` | boolean | No |  |
| `--snoozable-on-all-steps` | boolean | No |  |
| `--snooze-duration` | object | No | How long a snooze lasts. |
| `--snooze-label` | string | No |  |
| `--template-source` | string | No |  |
| `--show-step-counter` | boolean | No |  |
| `--step-counter-format` | string | No |  |
| `--tags` | array | No | JSON array, or a comma-separated list for strings. |
| `--variants` | array | No | JSON array, or a comma-separated list for strings. |
| `--latest-version` | integer | Yes | Expected `latest_version` from the last GET with `include_unpublished_changes=true`. |

Requires the `surveys:write` scope.

## `amp surveys archive`

Archives an unpublished survey. A survey counts as published while its flag is enabled, unless it's only in test mode without a schedule; archiving a published survey returns `409` with `error_code: cannot_archive_published`. Unpublish it in Amplitude first. Use `dry_run=true` to check whether a survey can be archived. An already archived survey returns `404`, like `GET`.

Requires --yes to apply changes, or --dry-run when supported to validate without applying changes.

```bash
amp surveys archive --project <project_id> --survey <survey_id> --dry-run
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--survey` | string | Yes | Survey nudge identifier. Alias: `--survey-id`. |
| `--dry-run` | boolean | No | Validate request without performing mutation. |
| `--idempotency-key` | string | No | Generated automatically when omitted. Header acceptance alone does not guarantee retry deduplication. |

Requires the `surveys:write` scope.

