---
title: TimeSeries History
slug: timeseries-history
docTags: 
createdAt: 2023-03-22T19:17:49.000Z
---

The TimeSeries History table stores the historic values of the tags registered in [TimeSeries Configuration](docId\:pVnXfCAcsh2SGha-9zoGJ). Every reading is numeric.

The unique constraint on this table is **sourceWellId + sourceTimeSeriesId + timestamp**. Re-posting an existing timestamp for the same tag upserts (overwrites) the previous value, and if a payload carries the same point twice, one row is written.

:::hint{type="warning"}
**TimeSeries Configuration** for a given **sourceTimeSeriesId** must be added to the system before attempting to add **TimeSeries History** to that **sourceTimeSeriesId**.
:::

| **Variable**       | **Data Type**   | **Is Nullable?** | **Description**                                                                                                                                                                                                                                      |
| ------------------ | --------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sourceWellId       | String          | No               | Source ID for the well<br /><br />**From WellView:** wvwellheader table, idwell column<br />**From OpenWells:** cd\_well table, well\_id column                                                                                                      |
| sourceTimeSeriesId | String          | No               | Time series tag identifier, which must already exist in [TimeSeries Configuration](docId\:pVnXfCAcsh2SGha-9zoGJ)<br /><br />**OSI PI Use Tag ID:**<br />xxx.yyy.zzz<br /><br />**OSI PI AF use AttributeID**:<br />\\\server\\\element\\\attributeID |
| timestamp          | Datetime Offset | No               | Timestamp of the reading. Datetime offset (with timezone) in ISO 8601 format. Example: 2022-09-27T16:28:37+0000                                                                                                                                      |
| value              | Double          | No               | The numeric value of the reading, in the unit of measure declared on the tag's configuration                                                                                                                                                         |

***

# Data Integrity Checks

| **Condition**                                                                | **Response**    |
| ---------------------------------------------------------------------------- | --------------- |
| (sourceWellId, sourceTimeSeriesId) does not match a TimeSeries Configuration | Row Rejected    |
| sourceWellId, sourceTimeSeriesId, timestamp, or value is null                | Record Rejected |
| Duplicate (tag + timestamp)                                                  | Record Upserted |

:::hint{type="info"}
**Partial success on bulk ingest**

Unlike configuration upserts, history ingest does not abort the batch on bad rows. All valid rows are written first; rows referencing an unknown (sourceWellId, sourceTimeSeriesId) pair are then reported in the error response. An error response therefore does not mean nothing was written — check the message, which states how many rows were written and which pairs were rejected.
:::

***

# Common Error Messages

| **API**          | **Scenario**                     | **Error Response**                                                                                                       |
| ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Bulk add history | Some rows reference unknown tags | TimeSeries history upsert wrote N row(s) but rejected rows for M unknown (sourceWellId, sourceTimeSeriesId) pair(s): ... |