SymetryML Documentation
Streams

Preview stream

Fetch a one-off sample `DataFrame` from a `kafka`/`nats` source without creating or registering any Data Source — purely a preview, with no side effects and no interaction with the create/start/stop/delete stream lifecycle or with [Poll stream](/docs/api-reference/streams/streams-poll-post)'s cache.

POST
/{user}/streams/preview

Fetch a one-off sample DataFrame from a kafka/nats source without creating or registering any Data Source — purely a preview, with no side effects and no interaction with the create/start/stop/delete stream lifecycle or with Poll stream's cache.

Authorization

SymetryMLAuth
AuthorizationBearer <token>

HMAC-SHA256 signature-based authentication: requests are signed with your secret key and sent with the Customer-ID, Sym-date, Authorization, Content-MD5 and sym-version headers. sym-version is required and must be 7.x (for example 7.0). See SymetryML REST API Security for the signature algorithm and a complete example.

In: header

Path Parameters

user*string

User/Customer identifier

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

body*string

Encrypted DSInfo

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/c1/streams/preview" \  -H "Content-Type: application/json" \  -d 'v2:2TYsk+/zj32PJvmeT7FY7mT9yn0IpjSN2KcM1mRkpZEwbDiTsm04CcXJYQWm2r42q0JZnvZ43pFg9hutZhonwtVZkg5x5W4Bk2rhZoAGhD1iCSREqWLRKgPvv2Gdw3yHJj0wEx9O70d21p9VF/uEDXtMsIgFSdZeuLNStZJoUYvWuSmDxMRGznKILNRw8FNTIdNlQ61TWBrTBcWVKFqQoA=='

500 rows were returned in the live capture this example is based on (abridged to 3 here). Names/types echo exactly what was supplied in the request DSInfo — the server does not validate them against the actual message content.

{  "statusCode": 200,  "statusString": "OK",  "values": {    "dataframe": {      "attributeNames": [        "viewtime",        "userid",        "pageid"      ],      "data": [        [          "1",          "User_3",          "Page_16"        ],        [          "11",          "User_4",          "Page_88"        ],        [          "21",          "User_5",          "Page_22"        ]      ],      "attributeTypes": [        "C",        "S",        "S"      ],      "errorHandling": 1    }  }}

{  "statusCode": 400,  "statusString": "Preview invalid DS Stream type [s3]",  "values": {}}

Empty
{  "statusCode": 500,  "statusString": "Generic Exception [java.lang.IllegalStateException: [SUB-90007] No matching streams for subject.]",  "values": {}}

Poll stream POST

Fetch the next available batch of records from a Kafka topic as a one-off `DataFrame`, independent of the create/start/stop/delete stream lifecycle above (NATS is not supported here). Each poller is cached server-side for 2 minutes of inactivity, keyed by the DSInfo's `name`, so repeated polls against the same name continue from where the previous poll left off rather than re-reading from the start. Two distinct call patterns exist, and they behave very differently — pick based on which matches your situation, not by symmetry with the request body's shape: * **`sid` query param, no body**: look up an already-registered Data Source (e.g. one created via [Create stream](/docs/api-reference/streams/projects-project-streams-create-post)). This is the clean path: on success, returns a plain `200` with the batch. Requires the Data Source to already exist under that name — this call does **not** register anything itself. * **request body, no `sid`**: the real usage pattern from the CLI's stream-poll commands, which always send DSInfo `type: "kafka-poll"`. **Only `kafka`/`nats` are accepted as valid stream types — `kafka-poll` never passes** — so this call unconditionally returns `statusCode: 400`, `statusString: "Preview invalid DS Stream type [kafka-poll]"`. However, the server does not return early on that failed validation — it falls through and polls Kafka anyway, so **`values.dataframe` still carries a real batch of records** on the very same 400 response. Treat `values.dataframe`'s presence, not `statusCode`, as the actual success signal for this call pattern. This body-based call also does not register the DSInfo as a Data Source (the registration branch is skipped along with the rest of the failed-validation path), so a later `sid`-only poll under the same name will not find it. If both `sid` and a body are supplied, `sid` wins and the body is ignored entirely — its (in)validity has no effect on that request.