Response format

This topic explains how to control response formats when retrieving stream data from the Stream Management service. Available formatting options depend on the stream-data retrieval endpoint.

Response format describes how the Stream Management service returns data. You can control two aspects:

• Media type, such as application/json or application/sds4.

• Response shape such as objects or tables.

For example, to request the first data point in verbose JSON, include the following headers in your stream-data retrieval request. Replace the {placeholders} with the relevant IDs from your account. This example shows the request path and format headers only.

GET /api/account/{accountId}/sds/{instanceId}/v2/Streams/{streamId}/Data/First HTTP/1.1

Accept: application/json

Accept-Verbosity: verbose

Although these headers are sent in the request, they specify how you want the response formatted. The sections below explain the Accept and Accept-Verbosity headers shown in this example and the available response formats in more detail.

Media type

A media type identifies the format of the response body. Set the request's Accept header to select a media type; the response's Content-Type header identifies the media type returned. For JSON responses, the Accept-Verbosity request header controls whether many default-valued properties are explicitly included in the response body.

JSON

To request the service's default JSON response, set the Accept header to either application/json or text/json and omit Accept-Verbosity. There is no difference in the JSON response body between these two settings.

For example, include this header in your request to receive default JSON:

Accept: application/json

Use default JSON for routine stream-data retrieval when your client handles omitted default-valued properties. Compared with verbose JSON, default JSON can produce smaller payloads while representing the same data points. Unlike SDS binary, it can be read with standard JSON tools and does not require an SDS binary decoder.

By default, many properties with default values are omitted to reduce payload size. For details, see Effect of JSON verbosity on the payload in this topic.

Verbose JSON

Verbose JSON is a JSON response that explicitly includes many properties with default values that default JSON omits. Use it when inspecting raw responses or exporting data to tools that need explicit property values. Choose default JSON for routine stream-data retrieval when your client handles omitted defaults and smaller payloads are preferred.

To request verbose JSON, set Accept to application/json or text/json and include a second header of Accept-Verbosity: verbose, using them in conjunction. Compared with default JSON, verbose JSON reduces the need to interpret omitted defaults but can increase payload size. Both JSON settings work with standard JSON tools. Unlike SDS binary, neither requires an SDS binary decoder.

For example, include these headers in your request to receive verbose JSON:

Accept: application/json

Accept-Verbosity: verbose

The header value verbose is case-insensitive. The option applies to JSON, not SDS binary formats, and does not enable pretty-printing or compression. Properties that the service explicitly excludes can remain absent even in verbose JSON.

For a detailed explanation of the differences between default and verbose JSON responses, see Effect of JSON verbosity on the payload in this topic.

SDS binary

SDS binary is a response format that represents data as bytes using SDS-specific encoding rather than JSON text. Use it when your client can decode SDS binary and your workflow does not require readable JSON. Unlike default or verbose JSON, SDS binary cannot be read with a standard JSON parser.

To request SDS binary, set the Accept header to application/sds, application/sds2, application/sds3, or application/sds4. These media types select SDS serialization versions 1, 2, 3, and 4, respectively. Choose a version supported by your client. The SDS binary serialization version is separate from the REST API version.

For example, include this header in your request to receive SDS binary serialization version 4:

Accept: application/sds4

For a new integration, use the latest SDS binary serialization version supported by both the service and your client, currently application/sds4. For an existing integration, continue using the version your client already supports and has been tested with. Before upgrading, verify that your client can decode the newer version and correctly read representative data.

The Accept-Verbosity header does not change SDS binary output.

Effect of JSON verbosity on the payload

A property's default value depends on its data type. For example:

• A non-nullable numeric property's default is 0

• A non-nullable Boolean property's default is false

• A nullable property's default is null. For a text property, null means no value; it is not the same as an empty string ("").

These are data-type defaults, not values copied from a stream type definition. For stream type codes and their default values, see SDS type codes.

When preparing a JSON response, the service uses the property's value and the requested verbosity to decide whether to write the property to the payload.

Verbosity does not change stored data, summary calculations, or the number of returned data points. Values omitted from the payload remain part of the underlying data and are still used in summaries and calculations.

The following examples compare default and verbose JSON responses for the same two data points in a Windtopia turbine stream. Each point has a timestamp property named Timestamp and a non-nullable numeric property named Value. The first point has a value of 0, and the second has a value of 42.

Default-value properties in default JSON

Default JSON may omit properties whose values equal their data-type defaults. For the first point, it can omit Value because 0 is the numeric default. The second point's Value is included because 42 is not the default.

Request default JSON without the verbosity header:

Accept: application/json

With this request header and no Accept-Verbosity header, the service can return the following JSON payload for the two data points. The first point's Value property is omitted because its value is 0, while the second point's Value remains explicit:

[

{ "Timestamp": "2026-10-22T12:00:00Z" },

{ "Timestamp": "2026-10-22T12:01:00Z", "Value": 42 }

]

When consuming default JSON, interpret omitted properties according to their data types. For example, an omitted non-nullable numeric property represents 0, whereas an omitted nullable numeric property represents null, not 0. A generic JSON parser does not automatically restore omitted properties; your client must handle them using the stream's type information.

Default-value properties in verbose JSON

Verbose JSON explicitly includes properties whose values equal their data-type defaults, unless the service explicitly excludes the property. It also includes properties whose values differ from their defaults. For these two points, Value is included for both 0 and 42.

Request verbose JSON to include the zero explicitly:

Accept: application/json

Accept-Verbosity: verbose

Adding Accept-Verbosity: verbose to the request makes the first point's zero explicit in the response payload. The same two data points are returned, but now both include Value:

[

{ "Timestamp": "2026-10-22T12:00:00Z", "Value": 0 },

{ "Timestamp": "2026-10-22T12:01:00Z", "Value": 42 }

]

Both responses represent the same two data points. Only the serialized properties differ. Omitting Value does not remove the first point or mean that its measurement is missing. The value 42 appears in both responses because it is not the property's default value.

Response shape

Response shape describes the layout of the returned payload. For stream-data retrieval endpoints that support row-column output, set the form query parameter in the request URL rather than using a header.

Use table format when you need results that are easy to load into analytics or reporting tools. These tools commonly expect tabular input, where each row represents one data point, and each column represents one property.

Use the form query parameter to return multi-value stream-data retrieval results and summaries in a tabular layout. Specify form=table to return Columns and Rows. Specify form=tableh to return the same structure, with column names in the first row of Rows.

Without form

When you omit the form query parameter, the endpoint uses its default response shape. For this range request, the data is returned as JSON objects rather than as a table with Columns and Rows:

[

{ "Timestamp": "2026-10-22T12:00:00Z" },

{ "Timestamp": "2026-10-22T12:01:00Z", "Value": 42 }

]

Each data point is an object whose property names identify the values. As with other default JSON responses, properties with default values may be omitted.

form=table

To retrieve data points starting at the specified timestamp in table format, include form=table in the request URL:

GET /api/account/{accountId}/sds/{instanceId}/v2/Streams/windtopia-turbine-01/Data/Range?startIndex=2026-10-22T12:00:00Z&count=2&form=table HTTP/1.1

Accept: application/json

The response describes each column in Columns and contains the data points as arrays in Rows. Each row's values follow the column order:

{

"Name": "windtopia-turbine-01",

"Columns": [

{ "Name": "Timestamp", "Type": "DateTime" },

{ "Name": "Value", "Type": "Double" }

],

"Rows": [

["2026-10-22T12:00:00Z", 0],

["2026-10-22T12:01:00Z", 42]

]

}

Unlike an omitted property in an object response, the zero remains explicit here because it occupies a position in the row array.

form=tableh

To include column names as the first row, change the query parameter to form=tableh:

GET /api/account/{accountId}/sds/{instanceId}/v2/Streams/windtopia-turbine-01/Data/Range?startIndex=2026-10-22T12:00:00Z&count=2&form=tableh HTTP/1.1

Accept: application/json

The response retains the same column definitions and data points, but adds a header row before the data rows:

{

"Name": "windtopia-turbine-01",

"Columns": [

{ "Name": "Timestamp", "Type": "DateTime" },

{ "Name": "Value", "Type": "Double" }

],

"Rows": [

["Timestamp", "Value"],

["2026-10-22T12:00:00Z", 0],

["2026-10-22T12:01:00Z", 42]

]

}

Treat the first row of Rows as column names, not as a data point. The request still retrieves two data points. The additional row contains only the headers.