# Method: admin.projects.locations.subscriptions.seek

- [HTTP request](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.response_body)
- [Authorization scopes](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#body.aspect)
- [NamedTarget](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#NamedTarget)

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`

Where `{endpoint}` is one of the [supported service endpoints](https://docs.cloud.google.com/pubsub/lite/docs/reference/rest#rest_endpoints).

The URLs use [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `name` | `string` Required. The name of the subscription to seek. Authorization requires the following [IAM](https://cloud.google.com/iam/docs/) 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 (`https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#NamedTarget`), "timeTarget": { object (`https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/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: ||
| `namedTarget` | ``enum (`https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.subscriptions/seek#NamedTarget`)`` Seek to a named position with respect to the message backlog. |
| `timeTarget` | ``object (`https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/TimeTarget`)`` 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 `https://docs.cloud.google.com/pubsub/lite/docs/reference/rest/v1/admin.projects.locations.operations#Operation`.

### Authorization scopes

Requires the following OAuth scope:

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

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

## NamedTarget

A named position with respect to the message backlog.

| Enums ||
|---|---|
| `NAMED_TARGET_UNSPECIFIED` | Unspecified named target. Do not use. |
| `TAIL` | Seek to the oldest retained message. |
| `HEAD` | Seek past all recently published messages, skipping the entire message backlog. |