---
title: Historian REST API
description: The Historian REST API provides access to create and configure Datasets, create and configure Tags, and read and write Tag data.
---

[Skip to content](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#main-content)

[More support](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new?hsLang=en)

[![FlowEmailHeader](https://docs.timebase.flow-software.com/hs-fs/hubfs/FlowEmailHeader.png?width=120&height=33&name=FlowEmailHeader.png)](https://flow-software.com/)

Open main navigation

Close main navigation

- [More support](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new)
- [Open a Support Ticket](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new)

[Open a Support Ticket](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new?hsLang=en)

 Search all Timebase documentation

- There are no suggestions because the search field is empty.

1. [Timebase Knowledge Base](https://docs.timebase.flow-software.com/knowledge-base?hsLang=en)
2. [Timebase Historian](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian?hsLang=en)

# Historian REST API

## The Historian REST API provides access to create and configure datasets, create and configure tags, and read and write tag data.

**[API Documentation](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#Swagger)**

[**GET Datasets API Call**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#GetDatasets)

[**GET Dataset API Call**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#GETDataset)

[**POST Dataset API Call - Update**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTDataset)

**[POST Datasets API Call - Create](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTDataset)**

**[Delete Datasets API Call - Create](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTDataset)**

[**GET Tags API Call**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#GETTags)

[**POST Tags API Call**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTTag)

**[DELETE Tags API Call](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTTag)**

[**GET Tag Data API Call - Single Tag**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#GETTagData)

**[GET Tag Data API Call - Multiple Tags](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#GETTagData)**

[**POST Tag Data API Call - Single Tag**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTTagData)

**[POST Tag Data API Call - Multiple Tags](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTTagData)**

[**POST Dataset Status API Call**](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian-public-rest-api#POSTDatasetStatus)

---

 

### **API Documentation**

The REST API documentation is available at:

`http://<HistorianHostnameOrIPAddress>:4511/api/help`

#### ![REST API Documentation](https://docs.timebase.flow-software.com/hs-fs/hubfs/REST%20API%20Documentation.png?width=670&height=377&name=REST%20API%20Documentation.png)

#### Authentication

For authentication, see [Securing your Timebase System](https://docs.timebase.flow-software.com/en/knowledge-base/pulse-introduction?hsLang=en)

### API Calls

The following REST API calls are available:

#### **GET Datasets**

`GET` **Datasets**  
URL `http://<yourServerAddressHere>:4511/api/datasets`

Returns an array of the configured datasets in the Real Time Historian with its purging rules.

**Return Schema:**

```
[  {    "n": "MQTT Data",   "pa": 7,   "ps": 0,   "s":  0.34553,   "c":  120,   "a": 7.342432 },  {   "n": "The Juice Factory",   "pa": 7,   "ps": 0,   "s": 0.34553,   "c": 120,   "a": 7.342432  } ]
```

- n - Name of the dataset (String)
- pa - Purge Age. Set in Days (Int 32)
- ps - Purge Size. Set in Gigs (Int 32)

#### **GET Dataset**

`GET` **Dataset **  
URL `http://<yourServerAddressHere>:4511/api/datasets/{dataset}`

Returns an object of the configured dataset in the Real Time Historian with its purging rules.

**Return Schema:**

```
{  "n": "The Juice Factory",  "pa": 7,  "ps": 0, "s": 0.34553, "c": 120, "a": 7.342432 }
```

- n - Name of the dataset (String)
- pa - Purge Age. Set in Days (Int 32)
- ps - Purge Size. Set in Gigs (Int 32)

**POST Dataset**

`POST` **Dataset **  
URL `http://<yourServerAddressHere>:4511/api/datasets/{dataset}`

Updates an existing dataset in the Real Time Historian

**Request Body:**

```
{    "n": "The Juice Factory", "pa": 14, "ps": 0 }
```

- n - Name of the dataset (String) \*required
- pa - Purge Age. Set in Days (Int 32) \*required
- ps - Purge Size. Set in Gigs (Int 32) \*required

**POST Datasets**

`POST` **Datasets **  
URL `http://<yourServerAddressHere>:4511/api/datasets`

Creates a new dataset in the Real Time Historian

**Request Body:**

```
{    "n": "The Juice Factory", "pa": 14, "ps": 0 }
```

- n - Name of the dataset (String) \*required
- pa - Purge Age. Set in Days (Int 32) \*required
- ps - Purge Size. Set in Gigs (Int 32) \*required

**DELETE Dataset**

`DELETE` **Datasets **  
URL `http://<yourServerAddressHere>:4511/api/datasets/{dataset}`

Deletes a dataset by name in the Real Time Historian.

This will delete all historized data. Please ensure that a backup of the dataset folder had been created if data retention is required

**URL parameter:**

**dataset**- Name of the dataset to be deleted

#### **GET Tags**

`GET` **Tags**

URL `http://:4511/api/datasets/{dataset}/tags`

Returns an array of tags stored within the particular dataset. Tags will be classified between System generated diagnostics tags and user generated tags in the response.

Each dataset will have "System Tags" and "User Tags". User tags are tags either stored by a collector or inserted by the API. "System Tags" are related to diagnostic information about process specific parameters and dataset activity, like read and write speeds etc. Please see [this article](https://docs.timebase.flow-software.com/en/knowledge-base/system-tag-explanation?hsLang=en) explaining System Tags

**Optional URL parameter:**

**contains** - Filter criteria for tags to be returned (String)

**Return Schema:**

```
{  "n": "FL001.State", "d": "Filler 1 State", "u":  {  "0": "Idle",  "10": "Startup",  "20": "Running",  "21": "Bottle starvation",  "22": "Bottle jam",  "23": "Downstream bottleneck",  "30": "Cleaning" }, "fl":  {  "Measure": "State",  "Product": "Juice",  "Area Code": "131",  "Equipment": "Filler",  "Equipment Number": "1" },"t": "System.Integer"}
```

- n - Name of the tag (String)
- d - Description of the tag (String)
- f - Format of the value (String)
- u - Unit of Measure or State Enumeration (dictionary \<Int32,String\>)
- fl- Fields. Metadata associated with a tag (dictionary \<String,String\>)
- t - Data Type of the tag

#### **POST Tags**

`POST` **Tags**

URL `http://:4511/api/datasets/{dataset}/tags`

Updates or creates an array of tags stored within the particular dataset. If the dataset does not exist, it will be created automatically.

**Request Body:**

```
[ {  "n": "string",  "d": "string",  "f": "string",  "u":   {   "additionalProp1": "string",   "additionalProp2": "string",   "additionalProp3": "string"  },  "fl":   {   "additionalProp1": "string",   "additionalProp2": "string",   "additionalProp3": "string"  }, "t": "string" }]
```

- n - Name of the tag (String) \*required
- d - Description of the tag (String)
- f - Format of the value (String)
- u - Unit of Measure or State Enumeration (dictionary \<Int32,String\>)
- fl- Fields. Metadata associated with a tag (dictionary \<String,String\>

#### **Delete Tags**

`POST` **Tags**

URL `http://:4511/api/datasets/{dataset}/tags`

Removes an array of tags stored within the particular dataset. 

**Request Body:**

```
[ "tag1", "tag2", "tag3"]
```

- Array - Array of tag names (String) \*required to be removed

#### **POST Tag**

`POST` **Tag**

URL `http://:4511/api/datasets/{dataset}/tags/{tagname}`

Updates or creates a tag stored within the particular dataset. 

**Request Body:**

```
{ "n": "string", "d": "string", "f": "string", "u":   {   "additionalProp1": "string",   "additionalProp2": "string",   "additionalProp3": "string"  }, "fl":   {   "additionalProp1": "string",   "additionalProp2": "string",   "additionalProp3": "string"  }, "t": "string"}
```

- n - Name of the tag (String) \*required
- d - Description of the tag (String)
- f - Format of the value (String)
- u - Unit of Measure or State Enumeration (dictionary \<Int32,String\>)
- fl- Fields. Metadata associated with a tag (dictionary \<String,String\>)
- t - Data Type of the tag

#### **GET Tag Data - Single Tag**

This endpoint will become deprecated from version 1.1 onwards. Will be replaced by endpoint with the capability to read data for multiple tags in one request

`GET` **Tag Data**

URL `http://:4511/api/datasets/{dataset}/data/{tagname}`

Returns the data from the requested tag as stored in the referenced dataset.

Start and end time can either be supplied in standard ISO notation or UNIX format.

Relative time can also be specified for either start or end times.

If no times are specified in the request, the latest point will be returned.

If no end time is specified, it will default to "now".

**Optional URL parameter:**

**start** - Start timestamp to return data. ISO format

**end** -End timestamp to return data. ISO format

**unixStart** - Start timestamp to return data. UNIX Format

**unixEnd** - End timestamp to return data. UNIX Format

**relativeStart** - Relative start time i.e -2h

**relativeEnd** - Relative end time i.e -1h

`Relative` time periods include:

`y` - Years

`M` - Months

`d` - Days

`h` - Hours

`m` - Minutes

**Return Schema:**

```
{ "t":   {   "n": "Process.Memory",   "d": "Process memory usage",   "f": "0.0",   "u":     {     "1": "MB"    }  }, "s": "2024-10-02T16:12:58.716699Z", "e": "2024-10-02T16:12:58.716699Z", "d":   [   {    "t": "2024-10-02T16:12:53.643451Z",    "v": 615.0390625,    "q": 192   }  ]}
```

- t - tag object
- s - start time
- e - end time
- d - TVQ array of data

#### **GET Tag Data - Multiple Tags**

`GET` **Tag Data**

URL `http://:4511/api/datasets/{dataset}/data`

Returns the data from the requested tags as stored in the referenced dataset.

Start and end time can either be supplied in standard ISO notation or UNIX format.

Relative time can also be specified for either start or end times.

If no times are specified in the request, the latest point will be returned.

If no end time is specified, it will default to "now".

**Required URL parameter**

**tagname -** One or more tagnames. Specified as multiple `tagname` query parameters (e.g. ... ?`tagname`=131-TT-001.PV&`tagname`=131-TT-002.PV

**Optional URL parameter:**

**start** - Start timestamp to return data. ISO format

**end** -End timestamp to return data. ISO format

**unixStart** - Start timestamp to return data. UNIX Format

**unixEnd** - End timestamp to return data. UNIX Format

**relativeStart** - Relative start time i.e -2h

**relativeEnd** - Relative end time i.e -1h

`Relative` time periods include:

`y` - Years

`M` - Months

`d` - Days

`h` - Hours

`m` - Minutes

**Return Schema:**

```
{ "t":   {   "n": "Process.Memory",   "d": "Process memory usage",   "f": "0.0",   "u":     {     "1": "MB"    }  }, "s": "2024-10-02T16:12:58.716699Z", "e": "2024-10-02T16:12:58.716699Z", "d":   [   {    "t": "2024-10-02T16:12:53.643451Z",    "v": 615.0390625,    "q": 192   }  ]}
```

- t - tag object
- s - start time
- e - end time
- d - TVQ array of data

#### **POST Tag Data - Single Tag**

`POST` **Tag Data**

URL `http://:4511/api/datasets/{dataset}/data/{tagname}`

Post array of TVQ values to a tag in a particular dataset.

Request Body:

```
[ {  "t": "2024-10-02T16:16:50.989Z",  "v": "string",  "q": 0 }]
```

- t - timestamp
- v - value
- q - quality

Currently, inserting TVQs with a timestamp in the past/before current data points will be ignored. 

#### **POST Tag Data - Multiple Tags**

`POST` **Tag Data**

URL `http://:4511/api/datasets/{dataset}/data`

Post array of TVQ values for multiple tags in a particular dataset.

Request Body:

```
{  "131-TT-001.PV": [    {      "t": "2024-10-29T19:59:56.256Z",      "v": 56.788747,      "q": 192    },    {      "t": "2024-10-29T20:00:24.852Z",      "v": 57.957364,      "q": 192    }  ],  "131-TT-002.PV": [    {      "t": "2024-10-29T19:58:57.236Z",      "v": 57.123747,      "q": 192    },    {      "t": "2024-10-29T20:01:25.832Z",      "v": 56.967894,      "q": 192    }  ]}
```

- t - timestamp
- v - value
- q - quality

Currently, inserting TVQs with a timestamp in the past/before current data points will be ignored. 

#### **POST Dataset Status**

`POST` **Dataset Status**

URL `http://:4511/api/datasets/{dataset}/status`

Post a TVQ value to mark the current status of a dataset. To be used to handle loss of comms etc.

Request Body:

```
[ {  "t": "2024-10-02T16:16:50.989Z",  "v": "string",  "q": 0 }]
```

- t - timestamp
- v - value
- q - quality

Standard quality codes and values to be used include:

- `null` value and `64` quality, collector's heartbeat has not been detected for 10 seconds, all collector's tags set to `Store Forward`
- `null` value and `28` quality, collector has shutdown
- `null` value and `24` quality, collector is communicating with the Historian, but the collector has lost communication with its data source

- [Software Releases](https://docs.timebase.flow-software.com/knowledge-base/software-releases?hsLang=en)
- [Timebase Quick Start](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#main-content)

    - [Start Here!](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#start-here)
    - [System Requirements](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#system-requirements)
    - [Advanced Topics](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#advanced-topics)
- [Timebase Historian](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian?hsLang=en)
- [Timebase Data Collectors](https://docs.timebase.flow-software.com/knowledge-base/timebase-data-collectors?hsLang=en)
- [Timebase Explorer](https://docs.timebase.flow-software.com/knowledge-base/timebase-explorer?hsLang=en)
- [Timebase Pulse](https://docs.timebase.flow-software.com/knowledge-base/timebase-pulse?hsLang=en)
- [Windows Services Starter](https://docs.timebase.flow-software.com/knowledge-base/windows-services-starter?hsLang=en)

Copyright © 2025, Flow Software