# Method: projects.snapshots.create

- [HTTP request](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.response_body)
- [Authorization scopes](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#body.aspect)
- [Try it!](https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots/create#try-it)

Creates a snapshot from the requested subscription. Snapshots are used in [subscriptions.seek](https://cloud.google.com/pubsub/docs/replay-overview) operations, which allow you to manage message acknowledgments in bulk. That is, you can set the acknowledgment state of messages in an existing subscription to the state captured by a snapshot. If the snapshot already exists, returns `ALREADY_EXISTS`. If the requested subscription doesn't exist, returns `NOT_FOUND`. If the backlog in the subscription is too old -- and the resulting snapshot would expire in less than 1 hour -- then `FAILED_PRECONDITION` is returned. See also the `Snapshot.expire_time` field. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription, conforming to the [resource name format](https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names). The generated name is populated in the returned Snapshot object. Note that for REST API requests, you must specify a name in the request.

### HTTP request

Choose a location:
<button value="global" default="">global</button>   
`PUT https://pubsub.googleapis.com/v1/{name}`

<br />

### Path parameters

| Parameters ||
|---|---|
| `name` | `string` Required. User-provided name for this snapshot. If the name is not provided in the request, the server will assign a random name for this snapshot on the same project as the subscription. Note that for REST API requests, you must specify a name. See the [resource name rules](https://cloud.google.com/pubsub/docs/pubsub-basics#resource_names). Format is `projects/{project}/snapshots/{snap}`. |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "subscription": string, "labels": { string: string, ... }, "tags": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `subscription` | `string` Required. The subscription whose backlog the snapshot retains. Specifically, the created snapshot is guaranteed to retain: (a) The existing backlog on the subscription. More precisely, this is defined as the messages in the subscription's backlog that are unacknowledged upon the successful completion of the `snapshots.create` request; as well as: (b) Any messages published to the subscription's topic following the successful completion of the snapshots.create request. Format is `projects/{project}/subscriptions/{sub}`. |
| `labels` | `map (key: string, value: string)` Optional. See [Creating and managing labels](https://cloud.google.com/pubsub/docs/labels). An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `tags` | `map (key: string, value: string)` Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing" See <https://{$universe.dns_names.final_documentation_domain}/pubsub/docs/tags> for more information on using tags with Pub/Sub resources. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

### Response body

If successful, the response body contains a newly created instance of `https://docs.cloud.google.com/pubsub/docs/reference/rest/v1/projects.snapshots#Snapshot`.

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/pubsub`
- `https://www.googleapis.com/auth/cloud-platform`

For more information, see the [Authentication Overview](https://docs.cloud.google.com/docs/authentication#authorization-gcp).