Replaying and purging Pub/Sub Lite messages Stay organized with collections Save and categorize content based on your preferences.
- 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:
beginningorend
Seegcloud topic datetimes forinformation on time formats.
--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:
TAILfor the beginning orHEADfor 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:
- java-pubsublite: version 0.15.0.
- java-pubsublite-kafka: version 0.6.0.Consumers must also have auto-commit enabled.
- python-pubsublite: version 0.6.0.
- google-cloud-go: pubsublite version 0.10.0.
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:
trueto include only complete operations,falsetoinclude only active operationsLIMIT: 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.