Replaying and purging Pub/Sub Lite messages

Note: Pub/Sub Lite is deprecated. Effective March 18, 2026, Pub/Sub Lite will be turned down.
  • Current customers: Pub/Sub Lite remains functional until March 18, 2026.
    If you have not used Pub/Sub Lite within the 90-day period preceding July 15, 2025 (April 15, 2025 - July 15, 2025), you won't be able to access Pub/Sub Lite starting on July 15, 2025.
  • New customers: Pub/Sub Lite is no longer available for new customers after September 24, 2024.

You can migrate your Pub/Sub Lite service toGoogle Cloud Managed Service for Apache Kafka orPub/Sub.

This page shows how to initiate and track seek operations forLite subscriptions.

The Pub/Sub Lite seek feature allows you to replay and purge messages.It has the sameuse cases asPub/Sub seek. Unlike Pub/Sub, you do not need toconfigure Lite topics or subscriptions to use seek and there is no additionalcost.

The propagation of the seek to subscribers can be tracked using along-running operation.This is an API pattern used by Google Cloud products to track the progress oflong-running tasks.

Initiating seek

Pub/Sub Lite seek operations are initiated out-of-band (that is, fromthe Google Cloud CLI or separate Pub/Sub Lite API) and propagated tosubscribers. Online subscribers will benotified of the seek and react while they are live. Offline subscribers willreact to the seek once they are online.

You must specify a target location for the seek, which may be one of thefollowing:

  • Beginning of message backlog: Replays all retained messages. Note that theamount of available backlog is determined by theLite topic's message retention period andstorage capacity.
  • End of message backlog: Purges messages by skipping past all currentpublished messages.
  • Publish timestamp: Seeks to the first message with a (server-generated)publish timestamp greater than or equal to the specified timestamp. If no suchmessage can be located, seeks to the end of the message backlog. Subsequentmessages are guaranteed to have a publish timestamp greater than or equal tothe specified timestamp, with the exception of specified timestamps that arein the future.
  • Event timestamp: Seeks to the first message with an (user-specified) eventtimestamp greater than or equal to the specified timestamp. If no such messagecan be located, seeks to the end of the message backlog. As event timestampsare user supplied, subsequent messages may have event timestamps less than thespecified event time and should be filtered by the client, if necessary. Ifmessages do not have an event timestamp set, their publish timestamps are usedas a fallback.

You can initiate a seek for a Lite subscription with the Google Cloud CLI or thePub/Sub Lite API.

gcloud

To seek a Lite subscription, use thegcloud pubsub lite-subscriptions seekcommand:

gcloudpubsublite-subscriptionsseekSUBSCRIPTION_ID\--location=LITE_LOCATION\(--publish-time=PUBLISH_TIME|--event-time=EVENT_TIME|\--starting-offset=STARTING_OFFSET)\[--async]

Replace the following:

  • SUBSCRIPTION_ID: the ID of the Lite subscription

  • LITE_LOCATION: thelocation of the Lite subscription

  • PUBLISH_TIME: the publish timestamp to seek to

  • EVENT_TIME: the event timestamp to seek to

  • STARTING_OFFSET:beginning orend

Seegcloud topic datetimes forinformation on time formats.

Note: If you omit the--async flag, the command waits for the operation tocomplete. If subscribers are offline, the completion is delayed until they areonline. For more information, seetracking seek propagation.

If you specify the--async flag and the request is successful, the commandline displays the ID of the seek operation:

Check operation [projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID] for status.

Use thegcloud pubsub lite-operations describecommand to get the operation status.

REST

To seek a Lite subscription, send aPOST request like the following:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID:seekAuthorization: Bearer $(gcloud auth print-access-token)

Replace the following:

  • REGION: the region that the Lite subscription is in

  • PROJECT_NUMBER: the project number of the project with the Litesubscription

  • LITE_LOCATION: thelocation of the Lite subscription

  • SUBSCRIPTION_ID: the ID of the Lite subscription

To seek to the beginning or end of the message backlog, set the followingfields in the request body:

{"namedTarget":NAMED_TARGET}

Replace the following:

  • NAMED_TARGET:TAIL for the beginning orHEAD for the end ofthe message backlog.

To seek to a publish timestamp, set the following fields in the request body:

{"timeTarget":{"publishTime":TIMESTAMP}}

Specify"eventTime" to seek to an event timestamp.

Replace the following:

  • TIMESTAMP: A timestamp in RFC 3339 UTC format, with nanosecondresolution and up to nine fractional digits. Examples:"2014-10-02T15:01:23Z" and"2014-10-02T15:01:23.045123456Z".

If the request is successful, the response is a long-running operation in JSONformat:

{  "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID,  ...}

Go

The following sample uses the major version of the Go Pub/Sub client library (v2). If you are still using the v1 library, seethe migration guide to v2.To see a list of v1 code samples, seethe deprecated code samples.

Before trying this sample, follow the Go setup instructions inQuickstart: Using Client Libraries.For more information, see thePub/Sub Go API reference documentation.

import("context""fmt""io""cloud.google.com/go/pubsublite")// seekSubscription initiates a seek operation for a subscription.funcseekSubscription(wio.Writer,projectID,region,zone,subIDstring,seekTargetpubsublite.SeekTarget,waitForOperationbool)error{// projectID := "my-project-id"// region := "us-central1"// zone := "us-central1-a"// subID := "my-subscription"// seekTarget := pubsublite.Beginning// waitForOperation := false// Possible values for seekTarget:// - pubsublite.Beginning: replays from the beginning of all retained//   messages.// - pubsublite.End: skips past all current published messages.// - pubsublite.PublishTime(<time>): delivers messages with publish time//   greater than or equal to the specified timestamp.// - pubsublite.EventTime(<time>): seeks to the first message with event//   time greater than or equal to the specified timestamp.// Waiting for the seek operation to complete is optional. It indicates when// subscribers for all partitions are receiving messages from the seek// target. If subscribers are offline, the operation will complete once they// are online.ctx:=context.Background()client,err:=pubsublite.NewAdminClient(ctx,region)iferr!=nil{returnfmt.Errorf("pubsublite.NewAdminClient: %w",err)}deferclient.Close()// Initiate an out-of-band seek for a subscription to the specified target.// If an operation is returned, the seek has been successfully registered// and will eventually propagate to subscribers.subPath:=fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s",projectID,zone,subID)seekOp,err:=client.SeekSubscription(ctx,subPath,seekTarget)iferr!=nil{returnfmt.Errorf("client.SeekSubscription got err: %w",err)}fmt.Fprintf(w,"Seek operation initiated: %s\n",seekOp.Name())ifwaitForOperation{_,err=seekOp.Wait(ctx)iferr!=nil{returnfmt.Errorf("seekOp.Wait got err: %w",err)}metadata,err:=seekOp.Metadata()iferr!=nil{returnfmt.Errorf("seekOp.Metadata got err: %w",err)}fmt.Fprintf(w,"Seek operation completed with metadata: %v\n",metadata)}returnnil}

Java

Before running this sample, follow the Java setup instructions inPub/Sub Lite Client Libraries.

importcom.google.api.gax.longrunning.OperationFuture;importcom.google.cloud.pubsublite.AdminClient;importcom.google.cloud.pubsublite.AdminClientSettings;importcom.google.cloud.pubsublite.BacklogLocation;importcom.google.cloud.pubsublite.CloudRegion;importcom.google.cloud.pubsublite.CloudRegionOrZone;importcom.google.cloud.pubsublite.CloudZone;importcom.google.cloud.pubsublite.ProjectNumber;importcom.google.cloud.pubsublite.SeekTarget;importcom.google.cloud.pubsublite.SubscriptionName;importcom.google.cloud.pubsublite.SubscriptionPath;importcom.google.cloud.pubsublite.proto.OperationMetadata;importcom.google.cloud.pubsublite.proto.SeekSubscriptionResponse;publicclassSeekSubscriptionExample{publicstaticvoidmain(String...args)throwsException{// TODO(developer): Replace these variables before running the sample.StringcloudRegion="your-cloud-region";charzoneId='b';// Choose an existing subscription.StringsubscriptionId="your-subscription-id";longprojectNumber=Long.parseLong("123456789");// True if using a regional location. False if using a zonal location.// https://cloud.google.com/pubsub/lite/docs/topicsbooleanregional=false;// Choose a target location within the message backlog to seek a subscription to.// Possible values for SeekTarget:// - SeekTarget.of(BacklogLocation.BEGINNING): replays from the beginning of all retained//   messages.// - SeekTarget.of(BacklogLocation.END): skips past all current published messages.// - SeekTarget.ofPublishTime(<timestamp>): delivers messages with publish time greater than//   or equal to the specified timestamp.// - SeekTarget.ofEventTime(<timestamp>): seeks to the first message with event time greater//   than or equal to the specified timestamp.SeekTargettarget=SeekTarget.of(BacklogLocation.BEGINNING);// Optional: Wait for the seek operation to complete, which indicates when subscribers for all// partitions are receiving messages from the seek target. If subscribers are offline, the// operation will complete once they are online.booleanwaitForOperation=false;seekSubscriptionExample(cloudRegion,zoneId,projectNumber,subscriptionId,target,waitForOperation,regional);}publicstaticvoidseekSubscriptionExample(StringcloudRegion,charzoneId,longprojectNumber,StringsubscriptionId,SeekTargettarget,booleanwaitForOperation,booleanregional)throwsException{CloudRegionOrZonelocation;if(regional){location=CloudRegionOrZone.of(CloudRegion.of(cloudRegion));}else{location=CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion),zoneId));}SubscriptionPathsubscriptionPath=SubscriptionPath.newBuilder().setLocation(location).setProject(ProjectNumber.of(projectNumber)).setName(SubscriptionName.of(subscriptionId)).build();AdminClientSettingsadminClientSettings=AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();try(AdminClientadminClient=AdminClient.create(adminClientSettings)){// Initiate an out-of-band seek for a subscription to the specified target. If an operation// is returned, the seek has been successfully registered and will eventually propagate to// subscribers.OperationFuture<SeekSubscriptionResponse,OperationMetadata>seekFuture=adminClient.seekSubscription(subscriptionPath,target);System.out.println("Seek operation "+seekFuture.getName()+" initiated successfully.");if(waitForOperation){System.out.println("Waiting for operation to complete...");seekFuture.get();System.out.println("Operation completed. Metadata:\n"+seekFuture.getMetadata().get());}}}}

Python

Before running this sample, follow the Python setup instructions inPub/Sub Lite Client Libraries.

fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.pubsubliteimportAdminClientfromgoogle.cloud.pubsublite.typesimportCloudRegion,CloudZone,SubscriptionPath# TODO(developer):# project_number = 1122334455# cloud_region = "us-central1"# zone_id = "a"# subscription_id = "your-subscription-id"# seek_target = BacklogLocation.BEGINNING# wait_for_operation = False# regional = True# Possible values for seek_target:# - BacklogLocation.BEGINNING: replays from the beginning of all retained#   messages.# - BacklogLocation.END: skips past all current published messages.# - PublishTime(<datetime>): delivers messages with publish time greater#   than or equal to the specified timestamp.# - EventTime(<datetime>): seeks to the first message with event time#   greater than or equal to the specified timestamp.# Waiting for the seek operation to complete is optional. It indicates when# subscribers for all partitions are receiving messages from the seek# target. If subscribers are offline, the operation will complete once they# are online.ifregional:location=CloudRegion(cloud_region)else:location=CloudZone(CloudRegion(cloud_region),zone_id)subscription_path=SubscriptionPath(project_number,location,subscription_id)client=AdminClient(cloud_region)try:# Initiate an out-of-band seek for a subscription to the specified# target. If an operation is returned, the seek has been successfully# registered and will eventually propagate to subscribers.seek_operation=client.seek_subscription(subscription_path,seek_target)print(f"Seek operation:{seek_operation.operation.name}")exceptNotFound:print(f"{subscription_path} not found.")returnifwait_for_operation:print("Waiting for operation to complete...")seek_operation.result()print(f"Operation completed. Metadata:\n{seek_operation.metadata}")

If the seek request is successful, the response is a long-running operation ID.See information abouttracking seek propagationbelow if you need to know when subscribers have reacted to the seek.

Supported clients

Seek operations require subscribers that use the followingPub/Sub Lite client libraries and minimum versions:

Note: Thejava-pubsublite-kafka client library also supports a different type of seek that can be initiated bysubscribers. This is different to the type of seek described on this page, whichis initiated out-of-band and pushed to subscribers. Both types of seeks shouldnot be initiated concurrently, as they would interfere with one another.

Seek operations do not work when Pub/Sub Lite is used withApache Beam orApache Spark because thesesystems perform their own tracking of offsets within partitions. The workaroundis to drain, seek and restart the workflows.

The Pub/Sub Lite service is able to detect a subscriber client thatdoes not support seek operations (for example, an old client library version orunsupported framework) and will abort the seek with aFAILED_PRECONDITIONerror status.

Tracking seek propagation

If a long-running operation ID is returned for the initial seek request, thismeans the seek was successfully registered in the Pub/Sub Lite serviceand will eventually propagate to subscribers (if the client is supported, asabove). The operation tracks this propagation and completes once subscribershave reacted to the seek, for all partitions.

If subscribers are online, it may take up to 30 seconds for them to receive theseek notification. Seek notifications are sent independently for each partition,thus partitions may not react to the seek at the same instant. If subscribersare offline, the seek operation will complete once they are online.

If a previous seek invocation hasn't finished propagating to subscribers, it isaborted and superseded by the new seek operation. Seek operation metadataexpires after 30 days, which effectively aborts any incomplete seek operations.

Seek operation status

You can get the status of a seek operation using the Google Cloud CLI, or thePub/Sub Lite API.

gcloud

To get details about a Lite operation, use thegcloud pubsub lite-operations describecommand:

gcloudpubsublite-operationsdescribeOPERATION_ID\--location=LITE_LOCATION

Replace the following:

  • OPERATION_ID: the ID of the Lite operation

  • LITE_LOCATION: thelocation of the Lite operation

If the request is successful, the command line displays metadata about theLite operation:

metadata:  '@type': type.googleapis.com/google.cloud.pubsublite.v1.OperationMetadata  createTime: '2021-01-02T03:04:05Z'  target: projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID  verb: seekname: projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID

REST

To get details about a Lite operations, send aGET request like thefollowing:

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_IDAuthorization: Bearer $(gcloud auth print-access-token)

Replace the following:

  • REGION: the region that the Lite operation is in

  • PROJECT_NUMBER: the project number of the project with the Liteoperation

  • LITE_LOCATION: thelocation of the Lite operation

  • OPERATION_ID: the ID of the Lite operation

If the request is successful, the response is a long-running operation in JSONformat:

{  "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID,  ...}

Listing seek operations

Completed and active seek operations can be listed using the Google Cloud CLI, orthe Pub/Sub Lite API.

gcloud

To list Lite operations in a project, use thegcloud pubsub lite-operations listcommand:

gcloud pubsub lite-operations list \    --location=LITE_LOCATION \    [--subscription=SUBSCRIPTION] \    [--done=DONE] \    [--limit=LIMIT]

Replace the following:

  • LITE_LOCATION: thelocation that the Lite operations are in

  • SUBSCRIPTION: filter operations by Lite subscription

  • DONE:true to include only complete operations,false toinclude only active operations

  • LIMIT: an integer to limit the number of operations returned

If the request is successful, the command line displays a summary of the Liteoperations:

OPERATION_ID  TARGET                                                                         CREATE_TIME           DONE   ERROR_CODE  MESSAGEoperation2    projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID  2021-05-06T07:08:00Z  Trueoperation1    projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID  2021-01-02T03:04:00Z  True

REST

To list Lite operations in a project, send aGET request like the following:

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operationsAuthorization: Bearer $(gcloud auth print-access-token)

Replace the following:

  • REGION: the region that the Lite operations are in

  • PROJECT_NUMBER: the project number of the project with the Liteoperations

  • LITE_LOCATION: thelocation that the Lite operations are in

If the request is successful, the response is a list of Lite operations inJSON format:

{  "operations": [      {          "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID",          ...      },      {          "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID",          ...      }  ]}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.