Get Stream

GET/api/v2/streams/datasets/{datasetRid}/streams/{streamBranchName}

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Get a stream by its branch name. If the branch does not exist, there is no stream on that branch, or the user does not have permission to access the stream, a 404 error will be returned.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:streams-read.

Path parameters

datasetRid

string

The Resource Identifier (RID) of a Dataset.

streamBranchName

string

The name of a Branch.

Query parameters

preview

boolean

optional

Enables the use of preview functionality.

Response body

Stream

object

Hide child attributes

branchName

string

The name of a Branch.

schema

object

The Foundry schema for this stream.

Show child attributes

viewRid

string

The view that this stream corresponds to.

partitionsCount

integer

The number of partitions for the Foundry stream. Defaults to 1.

Generally, each partition can handle about 5 mb/s of data, so for higher volume streams, more partitions are recommended.

streamType

string (enum)

A conceptual representation of the expected shape of the data for a stream. HIGH_THROUGHPUT and LOW_LATENCY are not compatible with each other. Defaults to LOW_LATENCY.

Enum values: LOW_LATENCY, HIGH_THROUGHPUT

compressed

boolean

Whether or not compression is enabled for the stream. Defaults to false.

Examples

Request

Copied!

curl \
\t-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v2/streams/datasets/ri.foundry.main.dataset.c26f11c8-cdb3-4f44-9f5d-9816ea1c82da/streams/master?preview=true"

Response

Copied!

{
  "schema": {
    "fields": [
      {
        "name": "timestamp",
        "schema": {
          "nullable": false,
          "dataType": {
            "type": "timestamp"
          }
        }
      },
      {
        "name": "value",
        "schema": {
          "nullable": false,
          "dataType": {
            "type": "string"
          }
        }
      }
    ],
    "keyFieldNames": [
      "timestamp"
    ]
  },
  "partitionsCount": 1,
  "streamType": "LOW_LATENCY",
  "branchName": "master",
  "viewRid": "ri.foundry-streaming.main.view.ecd4f0f6-8526-4468-9eda-14939449ad79",
  "compressed": false
}

Error responses

Error Name
`InvalidFieldSchema`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The field schema failed validations
	Parameters	`fieldName, message`
`InvalidStreamNoSchema`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The requested stream exists but is invalid, as it does not have a schema.
	Parameters	`datasetRid, branchName, viewRid`
`InvalidStreamType`	Error Code	`INVALID_ARGUMENT`
	Status Code	400
	Description	The stream type is invalid.
	Parameters	`streamType`
`StreamNotFound`	Error Code	`NOT_FOUND`
	Status Code	404
	Description	The given Stream could not be found.
	Parameters	`datasetRid, streamBranchName`

See Errors for a general overview of errors in the platform.