Performs an out-of-band seek for a subscription to a specified target, which may be timestamps or named positions within the message backlog. Seek translates these targets to cursors for each partition and orchestrates subscribers to start consuming messages from these seek cursors.
If an operation is returned, the seek has been registered and subscribers will eventually receive messages from the seek cursors (i.e. eventual consistency), as long as they are using a minimum supported client library version and not a system that tracks cursors independently of Pub/Sub Lite (e.g. Apache Beam, Dataflow, Spark). The seek operation will fail for unsupported clients.
If clients would like to know when subscribers react to the seek (or not), they can poll the operation. The seek operation will succeed and complete once subscribers are ready to receive messages from the seek cursors for all partitions of the topic. This means that the seek operation will not complete until all subscribers come online.
If the previous seek operation has not yet completed, it will be aborted and the new invocation of seek will supersede it.
HTTP request
POST https://{endpoint}/v1/admin/{name=projects/*/locations/*/subscriptions/*}:seek
Authorization requires the following IAM permission on the specified resource name:
pubsublite.subscriptions.seek
Request body
The request body contains data with the following structure:
JSON representation
{// Union field target can be only one of the following:"namedTarget": enum (NamedTarget),"timeTarget": {object (TimeTarget)}// End of list of possible types for union field target.}
Fields
Union field target. The target to seek to. Must be set. target can be only one of the following:
Seek to the first message whose publish or event time is greater than or equal to the specified query time. If no such message can be located, will seek to the end of the message backlog.
Response body
If successful, the response body contains an instance of Operation.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-06-17 UTC."],[],[],null,["# Method: admin.projects.locations.subscriptions.seek\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Request body](#body.request_body)\n - [JSON representation](#body.request_body.SCHEMA_REPRESENTATION)\n- [Response body](#body.response_body)\n- [Authorization scopes](#body.aspect)\n- [NamedTarget](#NamedTarget)\n\nPerforms an out-of-band seek for a subscription to a specified target, which may be timestamps or named positions within the message backlog. Seek translates these targets to cursors for each partition and orchestrates subscribers to start consuming messages from these seek cursors.\n\nIf an operation is returned, the seek has been registered and subscribers will eventually receive messages from the seek cursors (i.e. eventual consistency), as long as they are using a minimum supported client library version and not a system that tracks cursors independently of Pub/Sub Lite (e.g. Apache Beam, Dataflow, Spark). The seek operation will fail for unsupported clients.\n\nIf clients would like to know when subscribers react to the seek (or not), they can poll the operation. The seek operation will succeed and complete once subscribers are ready to receive messages from the seek cursors for all partitions of the topic. This means that the seek operation will not complete until all subscribers come online.\n\nIf the previous seek operation has not yet completed, it will be aborted and the new invocation of seek will supersede it.\n\n### HTTP request\n\n`POST https://{endpoint}/v1/admin/{name=projects/*/locations/*/subscriptions/*}:seek`\n\nWhere `{endpoint}` is one of the [supported service endpoints](/pubsub/lite/docs/reference/rest#rest_endpoints).\n\nThe URLs use [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n### Request body\n\nThe request body contains data with the following structure:\n\n### Response body\n\nIf successful, the response body contains an instance of [Operation](/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.operations#Operation).\n\n### Authorization scopes\n\nRequires the following OAuth scope:\n\n- `https://www.googleapis.com/auth/cloud-platform`\n\nFor more information, see the [Authentication Overview](https://cloud.google.com/docs/authentication/).\n\nNamedTarget\n-----------\n\nA named position with respect to the message backlog."]]
