---
title: "Get Time Series Entries"
url: "https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/get/get-entries"
version: "6.2"
language: "python"
---

# Get Time Series Entries

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/get/get-entries.md), [PHP](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/get/get-entries.php.md), [Node.js](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/get/get-entries.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Use `time_series_for.get` to retrieve a range of entries from a **single** time series.  
>   To retrieve a range of entries from **multiple** series,
>   use the [GetMultipleTimeSeriesOperation](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/operations/get.md#getmultipletimeseriesoperation) operation.
>
> - The retrieved data can be paged to get the time series entries gradually, one custom-size page at a time.
>
> - By default, the session will track the retrieved time series data.
>   See [disable tracking](https://docs.ravendb.net/6.2/client-api/session/configuration/how-to-disable-tracking.python.md) to learn how to disable.
>
> - When getting the time series entries,  
>   you can also *include* the series' **parent document** and/or **documents referred to by the entry tag**.  
>   Learn more [below](#include-parent-and-tagged-documents).
>
> - Calling `time_series_for.get` will result in a trip to the server unless the series' parent document was loaded  
>   (or queried for) with the time series included beforehand.  
>   Learn more in: [Including time series](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/include/overview.md).
>
> - In this page:
>   - [`Get` usage](#get-usage)
>   - [Examples](#examples)
>     - [Get all entries](#get-all-entries)
>     - [Get range of entries](#get-range-of-entries)
>     - [Get entries with multiple values](#get-entries-with-multiple-values)
>   - [Include parent and tagged documents](#include-parent-and-tagged-documents)
>   - [Syntax](#syntax)

## `Get` usage

- Open a session.
- Create an instance of `time_series_for` and pass it the following:
  - Provide an explicit document ID, -or-  
    pass an [entity tracked by the session](https://docs.ravendb.net/6.2/client-api/session/what-is-a-session-and-how-does-it-work.python.md#unit-of-work-pattern),
    e.g. a document object returned from [session.query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md)
    or from [session.load](https://docs.ravendb.net/6.2/client-api/session/loading-entities.python.md#load).
  - Specify the time series name.
- Call `time_series_for.get`.

## Examples

#### Get all entries:

In this example, we retrieve all entries of the "Heartrate" time series.  
The ID of the parent document is explicitly specified.

```python
# Get all time series entries
val = session.time_series_for("users/john", "HeartRates").get(datetime.min, datetime.max)
```

#### Get range of entries:

In this example, we query for a document and get its "Heartrate" time series data.

```python
# Query for a document with the Name property "John"
# and get its HeartRates time-series values
with store.open_session() as session:
  base_line = datetime.utcnow()

  query = session.query(object_type=User).where_equals("Name", "John")

  result = list(query)

  doc_id = session.advanced.get_document_id(result[0])

  val = session.time_series_for(doc_id, "HeartRates").get(datetime.min, datetime.max)

  session.save_changes()
```

#### Get entries with multiple values:

- Here, we check whether a stock's closing-time price is rising from day to day (over three days).  
  This example is based on the sample entries that were entered in [this example](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/append.python.md#append-entries-with-multiple-values).

- Since each time series entry contains multiple StockPrice values,
  we include a sample that uses [named](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/session/append.python.md#append-entries-with-multiple-values)
  time series values to make the code easier to read.

```python
going_up = False

# Use Get with a Named type
with store.open_session() as session:
  val = session.typed_time_series_for(StockPrice, "users/john").get()

  close_price_day_1 = val[0].value.close
  close_price_day_2 = val[1].value.close
  close_price_day_3 = val[2].value.close
  if close_price_day_2 > close_price_day_1 and close_price_day_3 > close_price_day_2:
      going_up = True
```

## Include parent and tagged documents

- When retrieving time series entries using `time_series_for.get`,  
  you can include the series parent document and/or documents referred to by the entries
  [tags](https://docs.ravendb.net/6.2/document-extensions/timeseries/overview.md#tags).

- The included documents will be cached in the session, and instantly retrieved from memory if loaded by the user.

- Use the following syntax to include the parent or tagged documents:

```python
# Get all time series entries
entries = session.time_series_for("users/john", "HeartRates").get_with_include(
  datetime.min,
  datetime.max,
  lambda builder: builder
  # Include documents referred-to by entry tags
  .include_tags()
  # Include Parent Document
  .include_document(),
)
```

## Syntax

```python
def get(
  self,
  from_date: Optional[datetime] = None,
  to_date: Optional[datetime] = None,
  start: int = 0,
  page_size: int = int_max,
) -> Optional[List[TimeSeriesEntry]]: ...
```

```python
# The strongly-typed API is used, to address time series values by name.
def get(
  self,
  from_date: Optional[datetime] = None,
  to_date: Optional[datetime] = None,
  start: int = 0,
  page_size: int = int_max,
) -> Optional[List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]]]: ...
```

| Parameter | Type | Description |
| - | - | - |
| **from\_date** (Optional) | `datetime` | Get the range of time series entries starting from this timestamp (inclusive). <br /> Default: `datetime.min` |
| **to\_date** (Optional) | `datetime` | Get the range of time series entries ending at this timestamp (inclusive). <br /> Default: `datetime.max` |
| **start** | `int` | Paging first entry. <br /> E.g. 50 means the first page would start at the 50th time series entry. <br /> Default: `0`, for the first time-series entry. |
| **page\_size** | `int` | Paging page-size. <br /> E.g. set `page_size` to 10 to retrieve pages of 10 entries. <br /> Default: `int_max`, for all time series entries. |

**Return Values (Optional)**

- `List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]]` - an array of time series entry classes.

```python
class TimeSeriesEntry:
  def __init__(self, timestamp: datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None):
      self.timestamp = timestamp
      self.tag = tag
      self.values = values
      self.rollup = rollup

  @property
  def value(self):
      if len(self.values) == 1:
          return self.values[0]
      raise ValueError("Entry has more than one value.")

  @value.setter
  def value(self, value: int):
      if len(self.values) == 1:
          self.values[0] = value
          return
      raise ValueError("Entry has more than one value")
```

- `TimeSeriesEntry<TValues>[]` - Time series values that can be referred to by name.

## See also

- [Time Series API Overview](https://docs.ravendb.net/6.2/document-extensions/timeseries/client-api/overview.md)
- [Studio Time Series Management](https://docs.ravendb.net/6.2/studio/database/document-extensions/time-series.md)
- [Time Series Querying](https://docs.ravendb.net/6.2/document-extensions/timeseries/querying/overview-and-syntax.python.md)
- [Time Series Indexing](https://docs.ravendb.net/6.2/document-extensions/timeseries/indexing.python.md)
- [Time Series Rollup and Retention](https://docs.ravendb.net/6.2/document-extensions/timeseries/rollup-and-retention.python.md)
