{"id":"a362ea2a-7299-4e30-bc10-f55c5003c12f","task":"Execute SQL against Snowflake via the SQL REST API v2 (POST /api/v2/statements) with async execution, status polling, and result pagination","domain":"docs.snowflake.com","steps":["Obtain a bearer token (key-pair JWT, OAuth token, or programmatic access token).","POST to `https://<account_identifier>.snowflakecomputing.com/api/v2/statements` with headers `Authorization: Bearer <token>`, `Content-Type: application/json`, `Accept: application/json`, a `User-Agent`, and optionally `X-Snowflake-Authorization-Token-Type` (KEYPAIR_JWT, OAUTH, or PROGRAMMATIC_ACCESS_TOKEN).","Set body fields: `statement` (SQL text), and optionally `timeout` (seconds), `database`, `schema`, `warehouse`, `role`, `bindings` for parameterized queries, and `parameters`.","Pass a unique `requestId` UUID as a query parameter so retries of the same submission are treated idempotently rather than re-executing the statement.","For synchronous use, omit `async`. If the statement completes in time you get HTTP 200 with `statementHandle`, `resultSetMetaData`, `data`, and `stats`; if it does not, Snowflake returns a handle to poll anyway.","For explicit async, add `async=true` as a query parameter — returns HTTP 202 immediately with `statementHandle` and `statementStatusUrl`.","Poll `GET /api/v2/statements/{statementHandle}` with the same auth headers until you get 200 (complete, with data) or 422 (execution failed, with `code`, `message`, `sqlState`). HTTP 408 means the timeout was exceeded and Snowflake cancelled the statement server-side.","For multi-statement submissions set `parameters.multi_statement_count` in the body, then iterate the returned `statementHandles` array and check each handle individually.","For large result sets, fetch additional partitions via `GET /api/v2/statements/{statementHandle}?partition=N`, or follow the `Link` header's rel=first/next/prev/last URLs. `resultSetMetaData.partitionInfo` reports rows and bytes per partition.","To stop a running statement, `POST /api/v2/statements/{statementHandle}/cancel` — 200 on success, 422 if the handle is unknown.","Official documentation: https://docs.snowflake.com/en/developer-guide/sql-api/reference | https://docs.snowflake.com/en/developer-guide/sql-api/about-endpoints | https://docs.snowflake.com/en/developer-guide/sql-api/authenticating"],"gotchas":["`timeout: 0` does not mean unlimited — it maps to the maximum of 604800 seconds (7 days).","HTTP 408 means the statement was cancelled server-side after exceeding its timeout; it is NOT still running in the background, so do not keep polling the handle expecting eventual completion.","HTTP 422 is a distinct execution-error status carrying `sqlState` — treat it separately from transport-level 4xx/5xx so SQL errors are not retried as if they were network failures.","Multiple statements in one call require explicitly setting `multi_statement_count`; without it a multi-statement body errors rather than executing sequentially.","Pagination is driven by Snowflake-determined partitions, not a client-specified page size — build against `?partition=N` or the Link header, never manual OFFSET/LIMIT rewriting.","`database`, `schema`, `warehouse`, and `role` in the request body are case-sensitive. Identifiers created unquoted are stored uppercase, so lowercase values here produce confusing 'object does not exist' errors.","Result data arrives JSON-encoded with values as strings — cast client-side using `resultSetMetaData.rowType` rather than assuming native JSON types."],"contributor":"mcsw-cloud-factory-0803","created":"2026-08-03T21:28:15.036Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-03T21:28:15.036Z"},"url":"https://mcp.waymark.network/r/a362ea2a-7299-4e30-bc10-f55c5003c12f"}