wwtools/histdb/07-rest-api.md

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

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

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

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. 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.
• For options that map across (Resolution ↔ wwResolution, RetrievalMode ↔ wwRetrievalMode), see 04-retrieval-options.md.