Snowpipe Streaming REST API endpoints¶

The Snowpipe Streaming REST API is designed for lightweight workloads and provides a flexible way to integrate with external applications without using a Snowpipe Streaming SDK.

This reference documents both ingestion modes:

• Elastic Channel endpoints for at-least-once ingestion without channel lifecycle or offset-token management.
• Named Channel endpoints for ordered, exactly-once ingestion.

Request headers¶

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

Direct REST clients must group rows into newline-delimited JSON (NDJSON), with one JSON object per line, and handle compression themselves. Both Elastic and Named Channel append requests have a 4 MB payload limit (the payload size sent over the network, after compression if used). Batch rows and use ZSTD or Gzip compression to reduce request overhead; bound batch size and elapsed time before sending.

Client requirements¶

A request that doesn’t meet the following requirements returns an HTTP 4xx error. These errors generally aren’t retryable, except for the cases in Retry policy.

The requirements are:

• Use the ingest hostname for your account, the documented HTTP method, and the documented request path and query parameters.
• Include the required headers with valid values, including Authorization and the content type the endpoint expects. When you compress a body, set Content-Encoding to gzip or zstd.
• Send a valid, unexpired authentication token whose role is authorized for the target account, pipe, and table.
• Stay within the account, channel, request, and byte-rate limits. For those limits, see Snowpipe Streaming high-performance limitations.

For retry delays, retryable status codes, and Named Channel recovery, see REST API error handling.

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:

<ingest-hostname>

The response body is the ingest hostname as plain text, not a JSON object.

Description of the response:

Exchange Scoped Token¶

The Exchange 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:

Response:

{
  "token": "string"
}

Description of response fields:

Elastic Channel endpoints¶

Elastic Channels don’t require a separate open-channel operation. Send a batch of NDJSON rows directly to a table or to the implicit ELASTIC channel of a pipe:

POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/tables/{tableName}/rows
POST /v2/streaming/data/databases/{databaseName}/schemas/{schemaName}/pipes/{pipeName}/channels/ELASTIC/rows

The table endpoint is only for Elastic Channels. On the first request, Snowflake creates or resolves the managed default pipe named <tableName>-STREAMING. Each streaming pipe includes an implicit ELASTIC channel, which the request uses without a separate open-channel operation. Use the pipe endpoint for an Elastic Channel on a custom pipe with in-flight transformations or pre-clustering.

Elastic request attributes¶

Send a non-empty NDJSON rowset. Elastic requests must not include continuationToken, offsetToken, startOffsetToken, or endOffsetToken.

Elastic response and delivery semantics¶

A successful HTTP 200 response is the durable acknowledgement: Snowflake has durably buffered the request payload. It doesn’t mean that rows are immediately queryable in the target table. Row-level processing errors are persisted to the error table when error logging is enabled.

{
  "message": "OK"
}

Elastic Channels provide at-least-once delivery without an ordering guarantee. Retrying after an ambiguous response can produce duplicate rows. Include a stable event identifier in the row payload and reconcile or deduplicate downstream when duplicates matter.

Elastic append example¶

export REQUEST_ID=$(uuidgen)

curl -sS -X POST \
  -H "Authorization: Bearer $SCOPED_TOKEN" \
  -H "Content-Type: application/x-ndjson" \
  "https://${INGEST_HOST}/v2/streaming/data/databases/$DB/schemas/$SCHEMA/tables/$TABLE/rows?requestId=$REQUEST_ID&retryCount=0" \
  --data-binary @rows.ndjson | jq .

For a retry of this rowset, reuse REQUEST_ID and increment retryCount. To use a custom pipe, replace the table path with /pipes/$PIPE/channels/ELASTIC/rows.

Named Channel endpoints¶

Named Channels require explicit channel lifecycle, continuation tokens, and source offset tokens. The following operations support ordered, exactly-once ingestion.

The following diagram shows the Named Channel request flow:

Open a Named 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:

Response:

{
  "next_continuation_token": "string",
  "channel_status": {
    "database_name": "string",
    "schema_name": "string",
    "pipe_name": "string",
    "channel_name": "string",
    "channel_status_code": "string",
    "last_committed_offset_token": "string",
    "created_on_ms": "long",
    "rows_inserted": "int",
    "rows_parsed": "int",
    "rows_error_count": "int",
    "last_error_offset_upper_bound": "string",
    "last_error_message": "string",
    "last_error_timestamp": "timestamp_utc",
    "snowflake_avg_processing_latency_ms": "int"
  }
}

Description of response fields:

Open channel requirements¶

• Use the same databaseName, schemaName, pipeName, and channelName for later open, append, drop, and status calls on that channel.
• Send open requests for one channel name one at a time. Overlapping open calls against the same name are rejected.
• Store next_continuation_token for the next append and last_committed_offset_token from this response when the open succeeds. For the recovery sequence, see Recover a Named Channel after a REST error.

Append rows to a Named Channel¶

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

Send this request to the ingest hostname returned by Get Hostname, not to your Snowflake account hostname. Set the continuationToken query parameter to the next_continuation_token value returned by the Open Channel request for the first request, and to the next_continuation_token value returned by the previous Append Rows response for each later request.

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

Named Channel append workflow¶

Every Named Channel append request must include a continuation token. Snowflake issues this token, and your client sends it back unchanged. You get the first token when you open the channel. Each successful append returns the token to use for the next append.

1. Call Open a Named Channel. In the JSON response body, read the top-level next_continuation_token field and save its value in your client.
2. Send an Append Rows request. Set these query parameters:
   • continuationToken: The saved token value, unchanged.
   • offsetToken: Your source offset for this batch, such as a Kafka offset. This value records exactly-once progress, and a later open-channel response returns it as last_committed_offset_token.
3. When the append succeeds, read next_continuation_token from the append response body. Replace your saved token with this new value, and discard the old one.
4. Repeat steps 2 and 3 for each batch.

Send appends for one channel one at a time. Wait for each append response before you send the next append, because the next request needs the token from that response.

The request body must be a non-empty NDJSON rowset, and the payload sent on the network must be 4 MB or smaller. For retries, see REST API retry policy. For Named Channel recovery, see Recover a Named Channel after a REST error.

Request:

Response:

{
  "next_continuation_token": "string"
}

Description of response fields:

Drop a Named Channel¶

The Drop Channel operation drops a Named Channel and its metadata on the server. Set fail_on_uncommitted_rows to true to reject the drop when uncommitted rows exist. If you leave it false, Snowflake can discard in-flight data.

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

Request:

Response:

This operation returns a payload with no specific successful response other than the HTTP status code.

Get Named Channel status in bulk¶

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:

Response:

{
  "channel_statuses": {
    "channel1": {
      "channel_status_code": "String",
      "last_committed_offset_token": "String",
      "database_name": "String",
      "schema_name": "String",
      "pipe_name": "String",
      "channel_name": "String",
      "rows_inserted": "int",
      "rows_parsed": "int",
      "rows_errors": "int",
      "last_error_offset_upper_bound": "String",
      "last_error_message": "String",
      "last_error_timestamp": "timestamp_utc",
      "snowflake_avg_processing_latency_ms": "int"
    },
    "channel2": {
      "comment": "same structure as channel1"
    }
    "comment": "potentially other channels"
  }
}

Description of channel_statuses fields for each channel:

Error response structure¶

The Snowpipe Streaming REST APIs return a JSON payload for error responses. This structure provides actionable information for both automated error handling and human analysis. For which status codes to retry, how to refresh authentication, and how to recover a Named Channel, see REST API error handling.

The response payload has the following structure:

{
  "code": "...",
  "message": "..."
}

Response fields¶

Example¶

The following example shows an error response you might receive:

{
  "code": "STALE_CONTINUATION_TOKEN_SEQUENCER",
  "message": "Channel sequencer in the continuation token is stale. Please reopen the channel"
}

This example shows the response for an attempt to use a continuation token with a stale channel sequencer. The code provides a clear, machine-readable identifier for the error, and the message offers a helpful, descriptive text for a user.