# Historian Data REST API

For when the consumer can't (or shouldn't) speak SQL — browsers, Excel, Power BI, Tableau, web frontends. Same data as the SQL extension tables, exposed as OData over HTTPS.

## Versions

Two API versions are supported by AVEVA Insight:

| Version | Recommended? | Notes |
| --- | --- | --- |
| `v2` | **Yes** | `TagFilter` (POST/GET) on `ProcessValues`, `AnalogSummary`, `StateSummary`. Single quotes are NOT used around `DateTime` in `$filter` (except for events). Summary entities use `StartDateTime` / `EndDateTime`; raw / process value entities use `DateTime`. |
| `v1` | Legacy | Still works. Uses `datetimeoffset'...'` quoting. Includes summary entities (`Summary`, `Daily`, `Hourly`, `Minutely`) that are v1-only. |

Pick **v2** for new code unless you need a v1-only summary entity.

## Authentication

Two flavors:

- **AVEVA Historian Insight (on-premises)** — Windows integrated security via Negotiate. The user must belong to `aaAdministrators`, `aaPowerUsers`, or `aaUsers`. Most modern browsers and Excel handle this transparently.
- **AVEVA Insight (cloud)** — OpenID Connect bearer-token, or Basic auth (`username` is treated as the API key). Some clients (older Excel) lack OIDC support; Basic remains as a fallback.

There's also a "solution-specific retrieval token" path: include the token in the URL and skip the `s/<solution_id>` segment.

## Endpoint shape

```
https://online.wonderware.com/s/<solution_id>/apis/historian/<api_version>/<resource>?<query_parameters>
```

- `<solution_id>` — your Insight solution. Omitted when using a solution-specific retrieval token.
- `<api_version>` — `v1` or `v2`.
- `<resource>` — one of the resources below.
- `<query_parameters>` — OData (`$filter`, `$top`, `$skip`, `$orderby`, `$select`, `$skiptoken`) or REST-style (`TagFilter=...&Resolution=...`).

In the URL: **`%20`** is space, **`%27`** is a single quote. The Chrome JSONView viewer also accepts `+` for space, which makes URLs more readable.

## OData operators

`eq`, `ne`, `gt`, `ge`, `lt`, `le`, `and`, `or`, `not`. Use parentheses for grouping. **A `$filter` may contain at most one time clause combined with one filter clause via `and`.** The filter clause itself may use any combination of operators internally.

If you need multiple values for the same field, use `or`:

```
((Priority eq 100 or Priority eq 200 or Priority eq 500) and (Severity le 2))
```

## `TagFilter` (REST-style)

Supported on `ProcessValues`, `AnalogSummary`, `StateSummary` (`v2`+). OData filter notation, with hard limits:

- Up to **20** `AND` clauses.
- Up to **20** `OR` clauses.
- Up to **2** UDF (user-defined function) clauses.
- **Cannot mix `AND` and `OR`** in the same `TagFilter`.
- Operators must be lowercase (`and`, not `And`).
- Most attribute searches are case-insensitive; case-sensitive ones are: `InterpolationType`, `MessageOn`, `MessageOff`.

Valid:

```
.../v2/ProcessValues?TagFilter=startswith(Source,'MVDS') and TagType eq 'string'
```

Invalid (mixed-case operator):

```
.../v2/ProcessValues?TagFilter=startswith(Source,'MVDS') And TagType eq 'string'
```

## Retrieval resources (the catalog)

| Resource | Verb(s) | Purpose |
| --- | --- | --- |
| `/ProcessValues` | GET | Raw value+time+quality (VTQ) records for one or more tags. |
| `/AnalogSummary` | GET | Aggregated analog statistics (min/max/avg/integral/etc.) over a window. |
| `/StateSummary` | GET | Time-in-state summaries for discrete/string/integer tags. |
| `/Events` | GET | Events and alarms (same content as the SQL `Events` table). |
| `/Tags` | GET / POST / DELETE | Tag metadata; v2 also returns extended properties. POST manages tags in bulk. |
| `/TagProperties` | GET | List of property names available on tags. |
| `/TagPropertyValues` | GET | Distinct values seen for a given tag property. |
| `/TagGroups` | GET | Groups of tags. |
| `/TagSuggest` | GET | Autocomplete-style tag-name suggestions. |
| `/TagSearch` | GET | Search tags by partial name / property. |
| `/TagExtendedProperties` | GET | Extended (custom) tag properties. |
| `/Summary` | GET | **v1-only.** Generic summary. |
| `/Daily`, `/Hourly`, `/Minutely` | GET | **v1-only.** Pre-bucketed summary periods. |
| `/SystemParameters` | GET | **On-premises only.** Server config. |

## `RetrievalMode` and `Resolution` (REST-side names)

Same modes as the SQL `wwRetrievalMode`. The REST query parameter is named `RetrievalMode`. Supported values from the v2 spec: `BestFit`, `Counter`, `Delta`, `Full`, `Interpolated`, `Maximum`, `Slope` (and `Cyclic`, the default for analog).

`Resolution` is in milliseconds, applies to `Raw`, `ProcessValues`, and the summary entities — picks the granularity of the returned data.

## `ProcessValues` — VTQ records

```http
GET /v2/ProcessValues?$filter=FQN+eq+'plant12.pump6'+and+DateTime+gt+2017-07-13T00:00:00Z
```

Required: `FQN` (`datasource.tagname`), and a time predicate (`DateTime` for v2). Optional: `OPCQuality`, `Value`, `Text` (string tags / discrete-tag message text). Returns 200 with `{ fqn, datetime, ... }`. 404 / 401 on missing FQN / unauthorized.

## `AnalogSummary` — windowed analog stats

```http
GET /v2/AnalogSummary
   ?$filter=FQN+eq+'Depot.Train09'
           +and+StartDateTime+ge+2017-06-09T09:00:00-07:00
           +and+EndDateTime+le+2017-06-09T10:00:00-07:00
   &Resolution=3600000
```

Required: `FQN`, `StartDateTime`, `EndDateTime` (RFC 3339 / ISO 8601, UTC `Z` or explicit offset). Optional: `RetrievalMode` (`Cyclic`/`Full`, default `Cyclic`), `Resolution`, `SliceBy` (split summary by another tag's value at the same time, up to 10 SliceBy tags), `SliceByValue` (filter criterion for SliceBy), `OPCQuality`. Quality logic mirrors the SQL `wwQualityRule = 'Good'`: all-Good → Good, full gap → Bad, mixed → Doubtful (`64`).

## `StateSummary` — windowed time-in-state

Same shape as `AnalogSummary` but for state-tag data. Use `RetrievalMode=Cyclic` and a `Resolution` to bucket by time.

## `Events` — alarms and events

```http
GET /v2/Events?$filter=EventTime+gt+'2017-07-13T00:00:00'
```

Note the **single quotes around the datetime** for events specifically — events break the v2 "no quotes" rule because `EventTime` is treated as a string-style column.

Filterable optional parameters include `ID` (alarm GUID), `EventTime`, `Type` (`Alarm.Set` / `Alarm.Acknowledge` / `Alarm.Clear` / `Alarm.Write` / `User.Write` / `User.Write.Secured` / `User.Write.Verified` / `Application.Write`), `Priority` (1-999, lower = higher), `Namespace`, `Severity` (1=Critical, 2=Major, 3=Minor, 4=Informational), `EventTimeUTCOffsetMins`, `ReceivedTime`, `IsAlarm`. **Property values are case-sensitive.**

## Pagination — `$skiptoken`

Responses larger than ~5000 records are paginated. The response body includes a `nextLink` containing `$skiptoken=...` — follow it to fetch the next page. You don't need to construct `$skiptoken` yourself.

## Worked browser query

```
https://online.wonderware.com/s/ik97r5/apis/historian/v2/ProcessValues
  ?$filter=FQN+eq+'Baytown.tank_level'
  +and+DateTime+gt+2017-07-13T00:00:00
  &$top=200
```

Returns up to 200 raw VTQ records since the timestamp.

## Excel / Power BI hookups

The PDF chapter (pp. 232-240) walks through:

- **Excel** — `Data → Get Data → From Web`, paste the OData URL, sign in. Excel can refresh the connection on demand.
- **Postman** — pick GET, paste URL, set Auth (Basic for cloud / Negotiate for on-prem), Send.
- **Power BI** — `Get Data → OData feed`, paste the resource root (`.../v2/ProcessValues` or similar), authenticate, then build the report.

The shape of the data Power BI sees is identical to a JSON pull, so any aggregation you'd do in Power Query mirrors what `$filter` would have selected server-side.

## SSRS — Reporting Services extension

The **AVEVA Historian SQL Server Reporting Services Extension** lets SSRS report builders consume the same `INSQL` linked server queries documented in [`05-query-recipes.md`](05-query-recipes.md). PDF p. 241. Useful when the consumer is corporate reporting infrastructure rather than ad-hoc analysts.

## Errors

| Code | Meaning |
| --- | --- |
| 200 | OK with body. |
| 401 Unauthorized | Token expired / missing membership in the `aa*` Windows groups. |
| 404 Not Found | FQN doesn't exist, or solution / resource path wrong. |
| 5xx | Historian / Insight server-side issue. Retry with backoff. |

## Cross-references

- For the full property catalog of each resource, see PDF chapter "Browser-Friendly Data Retrieval" pp. 183-240.
- For SQL equivalents of every retrieval mode the REST API exposes, see [`03-retrieval-modes.md`](03-retrieval-modes.md).
- For options that map across (`Resolution` ↔ `wwResolution`, `RetrievalMode` ↔ `wwRetrievalMode`), see [`04-retrieval-options.md`](04-retrieval-options.md).