# Replay a message in Pub/Sub by seeking to a snapshot or timestamp

Pub/Sub cannot retrieve the messages after you have acknowledged them. However, sometimes you might find it necessary to replay the acknowledged messages, for example, if you performed an erroneous acknowledgment. Then you can use the [Seek](https://docs.cloud.google.com/pubsub/docs/replay-overview.md.txt) feature to mark previously acknowledged messages as unacknowledged, and force Pub/Sub to redeliver those messages. You can also use seek to delete the unacknowledged messages by changing their state to acknowledged.

Seek to a [snapshot](https://docs.cloud.google.com/pubsub/docs/replay-message.md.txt#create_and_seek_to_snapshots) or seek to a [timestamp](https://docs.cloud.google.com/pubsub/docs/replay-message.md.txt#seek_to_a_timestamp) to replay the messages in a subscription. This guide shows examples of how to replay previously acknowledged Pub/Sub messages using seek.

*** ** * ** ***

To follow step-by-step guidance for this task directly in the
Google Cloud console, click **Guide me**:

[Guide me](https://console.cloud.google.com/freetrial?redirectPath=/http://console.cloud.google.com/?walkthrough_id%3Dpubsub--replay-from-snapshot)

*** ** * ** ***

## Before you begin

Complete the following steps before running your pipeline.

### Set up your project

<br />

### Required roles

To complete this quickstart, you need the following Identity and Access Management
(IAM) roles.


To get the permissions that
you need to complete this quickstart,

ask your administrator to grant you the
following IAM roles on your project:

- [Service Usage Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageAdmin) (`roles/serviceusage.serviceUsageAdmin`)
- [Pub/Sub Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/pubsub.md.txt#pubsub.editor) (`roles/pubsub.editor`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Using the `gcloud` Command-Line Interface

The easiest way to use gcloud is in the [Cloud Shell](https://docs.cloud.google.com/shell).
You can also use the command line tool
that comes with the [Google Cloud CLI](https://docs.cloud.google.com/sdk).
Setup prerequisites are met automatically for the gcloud CLI if you
create a brand new
[Compute Engine machine instance](https://console.cloud.google.com/compute/instances)
with access scopes including all Cloud APIs and the default Debian image. The
simplest way to create it is via the Compute Engine UI. For the rest of this
document, we will assume that you are using one of these command line tools.

For more information about using gcloud, see the [gcloud quickstart](https://docs.cloud.google.com/pubsub/docs/create-topic-gcloud).
Also see the [gcloud pubsub section](https://docs.cloud.google.com/sdk/gcloud/reference/pubsub) in the
[gcloud reference](https://docs.cloud.google.com/sdk/gcloud/reference.md.txt)
for a complete list of Pub/Sub `gcloud` commands.

### Create and Seek to Snapshots

Create a topic and a subscription. For better interactivity, use a short
acknowledgment deadline:

```bash
gcloud pubsub topics create seek-demo-topic
gcloud pubsub subscriptions create seek-demo-sub --topic=seek-demo-topic --ack-deadline=10
```

So far, no messages in the subscription have been
acknowledged. Capture this state by creating a snapshot:

```bash
gcloud pubsub snapshots create my-snapshot --subscription=seek-demo-sub
gcloud pubsub snapshots list
```

Now publish, pull, and acknowledge a message:

```bash
gcloud pubsub topics publish seek-demo-topic --message 'hello, world'
gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
```

Note that subsequent pulls yield no new messages (some transient duplicates are
possible):

```bash
gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
```

You can recover the message by seeking the subscription to the snapshot.
Note that the message may not be delivered instantly: Pub/Sub
does not guarantee message delivery latency. However, what is
guaranteed is that the messages retained in
the snapshot will be delivered at least once:

```bash
gcloud pubsub subscriptions seek seek-demo-sub --snapshot=my-snapshot
gcloud pubsub subscriptions pull seek-demo-sub --auto-ack
```

Note that you can seek other subscriptions to the same snapshot, as long as
the subscription's topic is the same as the snapshot's topic:

```bash
gcloud pubsub subscriptions create seek-demo-sub2 --topic=seek-demo-topic --ack-deadline=10
gcloud pubsub subscriptions seek seek-demo-sub2 --snapshot=my-snapshot
```

Pulling from `seek-demo-sub2` will now yield messages which were published before
`seek-demo-sub2` was created:

```bash
gcloud pubsub subscriptions pull seek-demo-sub2 --auto-ack
```

When you are done with the snapshot, clean up:

```bash
gcloud pubsub snapshots delete my-snapshot
```

### Seek to a timestamp

Another way to replay messages that have been acknowledged is to seek to a
timestamp. To seek to a timestamp, you must first configure the subscription to
retain acknowledged messages using `retain-acked-messages`. If
`retain-acked-messages` is set, Pub/Sub retains acknowledged
messages for 7 days.

You only need to do this step if you intend to seek to a timestamp, not to a
snapshot.

```bash
gcloud pubsub subscriptions update seek-demo-sub --retain-acked-messages
```

Now publish, pull, and acknowledge a message:

```bash
gcloud pubsub topics publish seek-demo-topic --message 'hello, world'
gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
```

The next pull should return no messages:

```bash
gcloud pubsub subscriptions pull seek-demo-sub
```

Now seek the subscription back in time to recover the message.
Note that the date arithmetic flags differ between the GNU and BSD (MacOS)
versions of the date command:

```bash
export TS_FORMAT=%Y-%m-%dT%H:%M:%SZ
gcloud pubsub subscriptions seek seek-demo-sub --time=$(date -u -d '-10 min' +$TS_FORMAT)
```

For more information about supported time formats,
see [gcloud topic datetimes](https://docs.cloud.google.com/sdk/gcloud/reference/topic/datetimes).

A subsequent pull should yield the message again:

```bash
gcloud pubsub subscriptions pull --auto-ack seek-demo-sub
```

You can also use seek to skip delivery of all messages published
before some point in time, such as the current time. To do this,
seek the subscription to the current time to mark as acknowledged all
past messages:

```bash
gcloud pubsub topics publish seek-demo-topic --message 'hello, world'
gcloud pubsub subscriptions seek seek-demo-sub --time=$(date -u +$TS_FORMAT)
```

After some propagation delay (\~60 seconds), the message will no longer
be delivered. You can check this by repeatedly executing the pull command
without acknowledging the message:

```bash
gcloud pubsub subscriptions pull seek-demo-sub
```

## Using the Cloud console

You can create snapshots, or seek to existing snapshots, in the subscription
detail page of the [Cloud console](https://console.cloud.google.com/cloudpubsub/subscriptions/).
For snapshot naming rules, see [Resource names](https://docs.cloud.google.com/pubsub/docs/pubsub-basics.md.txt#resource_names).

### Creating a snapshot

1. In the Google Cloud console, go to the **Pub/Sub subscriptions** page.

   [Go to the subscriptions page](https://console.cloud.google.com/cloudpubsub/subscription)
2. Select a subscription from the list.

3. Click **Create snapshot**.

4. Enter an ID for the snapshot, then click **Create** to save.

Snapshots can be viewed on the [snapshots page](https://console.cloud.google.com/cloudpubsub/snapshot) in the Google Cloud console. You can also manage snapshots in the
[details page of an individual topic](https://console.cloud.google.com/cloudpubsub/topicList).

### Replaying a subscription

The **Replay messages** dialog lets you seek to a previous time point or a saved snapshot. To open the dialog:

1. In the Google Cloud console, go to the **Pub/Sub subscriptions** page.

   [Go to the subscriptions page](https://console.cloud.google.com/cloudpubsub/subscription)
2. Select a subscription from the list.

3. Click **Replay messages**.

4. Under **Seek** , select either **To a previous time point** or **To a snapshot**, then select the time point or snapshot to seek to.

5. Click **Seek** to replay messages.

> [!NOTE]
> **Note:** To seek to a previous time point, your subscription must be configured to retain acknowledged messages. You can change this setting by clicking **Edit** on the subscription details page, and checking the box for **Retain acknowledged messages**.

## How did it go?

<button class="button button-blue expand-control gc-analytics-event" data-category="Quickstart" data-action="Feedback" data-label="Pub/Sub API, Client Libraries" data-value="1" track-type="quickstart" track-name="feedbackLink" track-metadata-position="steps" track-metadata-end-goal="itWorked"> It worked! </button>

> [!TIP]
> **Great!** What did you like about the quickstart? What could we have done better? [Let us know!](https://docs.cloud.google.com/pubsub/docs/replay-message.md.txt#).

<button class="button expand-control gc-analytics-event" data-category="Quickstart" data-action="Feedback" data-label="Pub/Sub API, Client Libraries" data-value="0" style="position: absolute; top: 0; left: 110px;" track-type="quickstart" track-name="feedbackLink" track-metadata-position="steps" track-metadata-end-goal="itFailed"> I got stuck. </button>

> [!WARNING]
> **We're sorry to hear that.** [Let us know what went wrong](https://docs.cloud.google.com/pubsub/docs/replay-message.md.txt#). We'll want to fix it.

Note that additional resources and links are available on the
[Pub/Sub support page](https://docs.cloud.google.com/pubsub/docs/support.md.txt).

## What's next

See [Replaying and discarding messages](https://docs.cloud.google.com/pubsub/docs/replay-overview.md.txt).