Snowpipe Streaming API REST endpoints

The following request headers apply to all the endpoints for the Snowpipe Streaming REST API:

Header

Description

Authorization

auth token

X-Snowflake-Authorization-Token-Type (optional)

JWT/OAuth

Get Hostname

The Get Hostname returns the hostname used to interact with the Snowpipe Streaming REST API. Each account has a unique hostname.

GET /v2/streaming/hostname

Response:

Field

Type

Description

status_code

int

Status code that customers can use to map internal errors with public documentation.

message

string

Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

hostname

string

The rowset hostname of the account.

Exchange Rowset Scoped Token

The Exchange Rowset Scoped Token returns a security token that can be used to access only the Snowpipe Streaming API-related service. This provides security protection for the customer.

POST /oauth/token

Request:

Attribute

Required

Component

Description

content_type

Yes

Header

“application/x-www-form-urlencoded”

grant_type

Yes

payload

urn:ietf:params:oauth:grant-type:jwt-bearer

scope

Yes

payload

The rowset hostname of the account

Response:

Field

Type

Description

status_code

int

Status code that customers can use to map internal errors with public documentation.

message

string

Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

token

string

The rowset scoped token.

Open Channel

The Open Channel operation creates or opens a new channel against a pipe or table. If the channel already exists, Snowflake bumps the client sequencer of the channel and returns the last committed offset token.

PUT /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Request:

Attribute

Required

Component

Description

databaseName

Yes

URI

Database name, case-insensitive

schemaName

Yes

URI

Schema name, case-insensitive

pipeName

Yes

URI

Pipe name, case-insensitive

channelName

Yes

URI

The name of the channel that you create or re-open, case-insensitive

offset_token

No

payload

String used to set an offset token when opening a channel.

requestId

No

Query parameter

UUID used to track requests through the system

Response:

Field

Type

Description

channel_status_code

String

Indicating the status of the channel.

last_committed_offset_token

String

Latest committed offset token

database_name

String

The name of the database that the channel belongs to.

schema_name

String

The name of the schema that the channel belongs to.

pipe_name

String

The name of the pipe that the channel belongs to.

channel_name

String

The name of the channel.

rows_inserted

int

A count of all rows inserted into this channel.

rows_parsed

int

A count of all rows parsed, but not necessarily inserted into this channel.

rows_errors

int

A count of all rows that experienced errors when inserting into this channel and were therefore rejected.

last_error_offset_upper_bound

String

Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order.

last_error_message

String

A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted.

last_error_timestamp

timestamp_utc

Timestamp at which the last error occured.

snowflake_avg_processing_latency_ms

int

Average e2e processing time for this channel.

Insert Row(s)

The Insert Rows operation inserts a batch of rows to the given channel.

POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}/rows

Request:

Attribute

Required

Component

Description

databaseName

Yes

URI

Database name, case-insensitive

schemaName

Yes

URI

Schema name, case-insensitive

pipeName

Yes

URI

Pipe, case-insensitive

channelName

Yes

URI

Channel name, case-insensitive

continuationToken

Yes for stateful clients, but not required for stateless clients

Query parameter

Continuation token from Snowflake, encapsulates both client and row sequencers

offsetToken

No

Query parameter

String used to set an offset token per batch.

rows

Yes

payload

Actual data payload that will be ingested in NDJSON format.

requestId

No

Query parameter

A UUID used to track requests through the system.

Response:

Field

Type

Description

status_code

int

Status code that customers can use to map internal errors with public documentation

next_continuation_token

string

The next continuation token from Snowflake, which encapsulates both client and row sequencers. It should be used for inserting the next batch.

message

string

Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

Drop Channel

The Drop Channel operation drops a channel at server side along with its metadata.

DELETE /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/{channelName}

Request:

Attribute

Required

Component

Description

databaseName

Yes

URI

Database name, case-insensitive

schemaName

Yes

URI

Schema name, case-insensitive

pipeOrTableName

Yes

URI

Pipe or table name, case-insensitive

channelName

Yes

URI

Channel name, case-insensitive

continuationToken

No

payload

Continuation token from Snowflake, which encapsulates both client and row sequencers. If it’s not provided, then we will delete the channel with the latest client sequencer.

requestId

No

Query parameter

A UUID used to track requests through the system

Response:

Field

Type

Description

status_code

int

Status code that customers can use to map internal errors with public documentation

message

string

Descriptive error message that explains the error when the response code is not 200 (Success). Otherwise, it’s empty for response code 200.

Bulk Get Channel Status

The Bulk Get Channel Status operation returns the status of a channel for a specific client sequencer.

POST /v2/streaming/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}:bulk-channel-status

Request:

Attribute

Required

Component

Description

databaseName

Yes

URI

Database name, case-insensitive

schemaName

Yes

URI

Schema name, case-insensitive

pipeName

Yes

URI

Pipe name, case-insensitive

channelName

Yes

Payload

An array of String channel names that the customer wants to get status for, case-sensitive.

Response:

Field

Type

Description

channel_status_code

String

Indicating the status of the channel.

last_committed_offset_token

String

Latest committed offset token

database_name

String

The name of the database that the channel belongs to.

schema_name

String

The name of the schema that the channel belongs to.

pipe_name

String

The name of the pipe that the channel belongs to.

channel_name

String

The name of the channel.

rows_inserted

int

A count of all rows inserted into this channel.

rows_parsed

int

A count of all rows parsed, but not necessarily inserted into this channel.

rows_errors

int

A count of all rows that experienced errors when inserting into this channel and were therefore rejected.

last_error_offset_upper_bound

String

Upper bound for the latest offset token of the inserted row set that has the last corresponding to an error. The real offset token of the row set with the last error is either this one or strictly before it in the channel ingestion order.

last_error_message

String

A human readable message corresponding to the latest error code for that channel, with sensitive customer data redacted.

last_error_timestamp

timestamp_utc

Timestamp at which the last error occured.

snowflake_avg_processing_latency_ms

int

Average e2e processing time for this channel.