---
type: api
title: Open a point in time
description: A search request by default runs against the most recent visible data of the target indices,
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-open-point-in-time
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/operation/operation-open-point-in-time
products:
  - Elasticsearch Serverless
---

# Open a point in time

Availability:

## Paths

- `POST` `/{index}/_pit`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/authentication#apikeyauth)

#### Path Parameters

- `index` (union IndexName | [] IndexName)
  A comma-separated list of index names to open point in time; use `_all` or empty string to perform the operation on all indices

## Description

A search request by default runs against the most recent visible data of the target indices,
which is called point in time. Elasticsearch pit (point in time) is a lightweight view into the
state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
search requests using the same point in time. For example, if refreshes happen between
`search_after` requests, then the results of those requests might not be consistent as changes happening
between searches are only visible to the more recent point in time.

A point in time must be opened explicitly before being used in search requests.

A subsequent search request with the `pit` parameter must not specify `index`, `routing`, or `preference` values as these parameters are copied from the point in time.

Just like regular searches, you can use `from` and `size` to page through point in time search results, up to the first 10,000 hits.
If you want to retrieve more hits, use PIT with `search_after`.

IMPORTANT: Each search request against a PIT returns in its response a `pit_id` field which may be different from the identifier you originally supplied.
Always use the most recently-received PIT identifier for the next request.
If you make concurrent search requests against the same PIT, Elasticsearch can return several different `pit_id` values in its responses.
In that case, use any of these values for later requests, preferring more recently-received values whenever possible.

When a PIT that contains shard failures is used in a search request, the missing are always reported in the search response as a `NoShardAvailableActionException` exception.
To get rid of these exceptions, a new PIT needs to be created so that shards missing from the previous PIT can be handled, assuming they become available in the meantime.

**Keeping point in time alive**

The `keep_alive` parameter, which is passed to a open point in time request and search request, extends the time to live of the corresponding point in time.
The value does not need to be long enough to process all data — it just needs to be long enough for the next request.

Normally, the background merge process optimizes the index by merging together smaller segments to create new, bigger segments.
Once the smaller segments are no longer needed they are deleted.
However, open point-in-times prevent the old segments from being deleted since they are still in use.

TIP: Keeping older segments alive means that more disk space and file handles are needed.
Ensure that you have configured your nodes to have ample free file handles.

Additionally, if a segment contains deleted or updated documents then the point in time must keep track of whether each document in the segment was live at the time of the initial search request.
Ensure that your nodes have sufficient heap space if you have many open point-in-times on an index that is subject to ongoing deletes or updates.
Note that a point-in-time doesn't prevent its associated indices from being deleted.
You can check how many point-in-times (that is, search contexts) are open with the nodes stats API.

## Required authorization

* Index privileges: `read`

## Query String Parameters

- `keep_alive` (string Duration)
  Extend the length of time that the point in time persists.
- `ignore_unavailable` (boolean · default: false)
  If `false`, the request returns an error if it targets a concrete (non-wildcarded)
index, alias, or data stream that is missing, closed, or otherwise unavailable.
If `true`, unavailable concrete targets are silently ignored.
- `preference` (string)
  The node or shard the operation should be performed on.
By default, it is random.
- `routing` (union Routing)
  A custom value that is used to route operations to a specific shard.
  One of: `string` or `string[]`
- `expand_wildcards` (string ExpandWildcards · default: open)
  The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether wildcard expressions match hidden data streams.
It supports comma-separated values, such as `open,hidden`.

Supported values include:
  - `all`: Match any data stream or index, including hidden ones.
  - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream.
  - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed.
  - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`.
  - `none`: Wildcard expressions are not accepted.
  Values: `all`, `open`, `closed`, `hidden`, `none`
- `allow_partial_search_results` (boolean · default: false)
  Indicates whether the point in time tolerates unavailable shards or shard failures when initially creating the PIT.
If `false`, creating a point in time request when a shard is missing or unavailable will throw an exception.
If `true`, the point in time will contain all the shards that are available at the time of the request.
- `max_concurrent_shard_requests` (number · default: 5)
  Maximum number of concurrent shard requests that each sub-search request executes per node.

## Request Body

`application/json`

- `index_filter` ({} QueryContainer) — optional
  Filter indices if the provided query rewrites to `match_none` on every shard.
  See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch-serverless/types/_types-query_dsl-querycontainer)

## Response

`application/json`

- `_shards` ({} ShardStatistics)
  Shards used to create the PIT
  - `failed` (number uint)
    The number of shards the operation or search attempted to run on but failed.
  - `successful` (number uint)
    The number of shards the operation or search succeeded on.
  - `total` (number uint)
    The number of shards the operation or search will run on overall.
  - `failures` ([] ShardFailure)
    - `index` (string IndexName)
    - `node` (string)
    - `reason` ({} ErrorCause)
      - `type` (string)
        The type of error
      - `reason` (union string) — nullable
        A human-readable explanation of the error, in English.
        One of: `string`
      - `stack_trace` (string)
        The server stack trace. Present only if the `error_trace=true` parameter was sent with the request.
      - `caused_by` ({} ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `root_cause` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
      - `suppressed` ([] ErrorCause) — recursive
        Same fields as `reason` in `failures`
    - `shard` (number)
    - `status` (string)
    - `primary` (boolean)
  - `skipped` (number uint)
- `id` (string Id)
## Code Examples

#### Console

```console
POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true
```

#### JavaScript

```javascript
const response = await client.openPointInTime({
  index: "my-index-000001",
  keep_alive: "1m",
  allow_partial_search_results: "true",
});
```

#### Python

```python
resp = client.open_point_in_time(
    index="my-index-000001",
    keep_alive="1m",
    allow_partial_search_results=True,
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.openPointInTime(o -> o
    .allowPartialSearchResults(true)
    .index("my-index-000001")
    .keepAlive(k -> k
        .time("1m")
    )
);
```

#### C#

```c#
var response = await client
    .OpenPointInTimeAsync(indices: new[] { "my-index-000001" }, d1 => d1
        .AllowPartialSearchResults(true)
        .KeepAlive("1m")
    );
```

#### PHP

```php
$resp = $client->openPointInTime([
    "index" => "my-index-000001",
    "keep_alive" => "1m",
    "allow_partial_search_results" => "true",
]);
```

#### Ruby

```ruby
response = client.open_point_in_time(
  index: "my-index-000001",
  keep_alive: "1m",
  allow_partial_search_results: "true"
)
```

## Response Examples

#### Open point in time response example1

A successful response from `POST /my-index-000001/_pit?keep_alive=1m&allow_partial_search_results=true`. It includes a summary of the total number of shards, as well as the number of successful shards when creating the PIT.

```json
{
  "id": "46ToAwMDaWR5BXV1aWQyKwZub2RlXzMAAAAAAAAAACoBYwADaWR4BXV1aWQxAgZub2RlXzEAAAAAAAAAAAEBYQADaWR5BXV1aWQyKgZub2RlXzIAAAAAAAAAAAwBYgACBXV1aWQyAAAFdXVpZDEAAQltYXRjaF9hbGw_gAAAAA=",
  "_shards": {
    "total": 10,
    "successful": 10,
    "skipped": 0,
    "failed": 0
  }
}
```