SQL API

Run SQL queries in your data warehouse.

The SQL API runs queries against your data warehouse through an existing connection and returns the rows. It is the most direct way to get data out of CARTO, and the same endpoint that Workflows calls when you trigger one via API.

Endpoint

What it does

GET /v3/sql/{connectionName}/query

Run a query

POST /v3/sql/{connectionName}/query

Run a query (POST)

POST /v3/sql/{connectionName}/job

Create a job

GET /v3/sql/{connectionName}/job/{jobId}

Get a job

DELETE /v3/sql/{connectionName}/job/{jobId}

Cancel a job

GET /v3/sql/jobs

List jobs

Choosing an endpoint

Your query

Use

Why

Short, and you want it cached

GET /query

Cached for 1 year. Fastest for repeated reads

Too long for a URL, or must always hit the warehouse

POST /query

Never cached, so every request costs warehouse compute

Longer than 1 minute

POST /job

Runs asynchronously. Poll the job for its status

Synchronous requests time out after 1 minute. If a query might exceed that — a large CREATE TABLE, a heavy aggregation — create a job instead and poll it rather than retrying the synchronous call.

Results are capped at 200,000 rows.

About `queryParameters` and parameterized queries

CARTO uses the native mechanisms available in each data warehouse to build parameterized queries, which prevents any SQL injection.

Therefore, to specify the parameters in the query and the expected syntax for queryParameters , you will need to use the specific providers' syntax:

BigQuery

BigQuery uses named parameters.

sqlQuery: 'SELECT * FROM carto-demo-data.demo_tables.retail_stores WHERE storetype = @type AND revenue > @minRevenue'
queryParameters: { 'minRevenue': 100000, 'type': 'Supermarket' },

Please note that empty arrays are not supported as parameter values.

Snowflake

Snowflake supports positional parameters, such as:

sqlQuery: 'SELECT * FROM demo_db.public.import_retail_stores WHERE storetype = :2 AND revenue > :1'
queryParameters: [100000, "Supermarket"],

Redshift and PostgreSQL

Snowflake supports positional parameters, such as:

sqlQuery: 'SELECT * FROM carto_demo_data.demo_tables.retail_stores WHERE storetype = $2 AND revenue > $1...'
queryParameters: [100000, "Supermarket"],

Endpoints

Run a query

get

/v3/sql/{connectionName}/query

Runs a SQL query and returns the result.

Times out after 1 minute. For longer queries, create a job instead.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Query parameters

qstringRequired

The SQL query, or the name of a named source.

Example: SELECT * FROM carto-demo-data.demo_tables.airports

queryParametersstringOptional

Values for the parameters in the query, as a JSON string. Named object on BigQuery, positional array on Snowflake, Redshift and PostgreSQL.

Example: {"minRevenue": 100000, "type": "Supermarket"}

vstring · enumOptional

API version. From 3.3, spatialDataColumn and spatialDataType replace geo_column.

Default: 3.0Possible values:

Responses

200

The query result.

application/json

The rows returned by the query, plus the schema of the result set. Responses are capped at 200,000 rows.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

408

The query took longer than the 1 minute timeout.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/sql/{connectionName}/query

GET /v3/sql/{connectionName}/query?q=text HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "rows": [
    {
      "name": "Madrid Barajas",
      "geom": {
        "type": "Point",
        "coordinates": [
          -3.56676,
          40.47225
        ]
      }
    }
  ],
  "schema": [
    {
      "name": "name",
      "type": "string"
    },
    {
      "name": "geom",
      "type": "geometry"
    }
  ]
}

Run a query (POST)

post

/v3/sql/{connectionName}/query

Same as the GET variant, for queries too long to fit in a URL.

This endpoint is not cached in CARTO's CDN, so every request reaches the data warehouse. Keep that in mind to avoid unnecessary compute cost.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Body

qstringRequired

The SQL query, or the name of a named source.

queryParametersone ofOptional

Values for the parameters in the query. A named object on BigQuery, a positional array on Snowflake, Redshift and PostgreSQL.

Responses

200

The query result.

application/json

The rows returned by the query, plus the schema of the result set. Responses are capped at 200,000 rows.

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

408

The query took longer than the 1 minute timeout.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/sql/{connectionName}/query

POST /v3/sql/{connectionName}/query HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 79

{
  "q": "SELECT * FROM carto-demo-data.demo_tables.airports",
  "queryParameters": {}
}

{
  "rows": [
    {
      "name": "Madrid Barajas",
      "geom": {
        "type": "Point",
        "coordinates": [
          -3.56676,
          40.47225
        ]
      }
    }
  ],
  "schema": [
    {
      "name": "name",
      "type": "string"
    },
    {
      "name": "geom",
      "type": "geometry"
    }
  ]
}

Create a job

post

/v3/sql/{connectionName}/job

Runs a query asynchronously. Use this for queries that would exceed the 1 minute timeout of the synchronous endpoints.

Available for BigQuery, Snowflake, Redshift, PostgreSQL and CARTO Data Warehouse connections.

Poll GET /v3/sql/{connectionName}/job/{jobId} with the returned externalId to follow the execution.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

Body

querystringRequired

The SQL query, or the name of a named source. Note this field is query, not q.

queryParametersone ofOptional

Values for the parameters in the query. A named object on BigQuery, a positional array on Snowflake, Redshift and PostgreSQL.

Responses

200

The job was created.

application/json

An asynchronous SQL job, as returned when it is created.

externalIdstringOptional

Use this to poll the job.

accountIdstringOptional

userIdstring · nullableOptional

connectionIdstringOptional

connectionNamestringOptional

providerIdstringOptional

createdAtstring · date-timeOptional

querystringOptional

tokenstring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/sql/{connectionName}/job

POST /v3/sql/{connectionName}/job HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "query": "CREATE TABLE your-project.your_dataset.airports_copy AS (SELECT * FROM carto-demo-data.demo_tables.airports)",
  "queryParameters": {},
  "metadata": {
    "source": "nightly-etl"
  }
}

{
  "externalId": "job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9",
  "accountId": "ac_jfakef5m",
  "userId": "auth0|61164b7xxx77c006a259f53",
  "connectionId": "5a32a0ea-555a-48dd-aeb1-8768aae8ef1c",
  "connectionName": "carto_dw",
  "providerId": "bigquery",
  "metadata": {
    "source": "nightly-etl"
  },
  "createdAt": "2026-07-30T16:10:35.732Z",
  "query": "CREATE TABLE your-project.your_dataset.airports_copy AS (SELECT * FROM carto-demo-data.demo_tables.airports)",
  "jobMetadata": {
    "location": "US"
  }
}

Get a job

get

/v3/sql/{connectionName}/job/{jobId}

Returns the current state of an asynchronous job.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

jobIdstringRequired

The job identifier.

Example: job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9

Responses

200

The job.

application/json

The state of an asynchronous SQL job.

jobIdstringOptional

connectionNamestringOptional

providerIdstringOptional

querystring · nullableOptional

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

createdAtstring · date-timeOptional

tokenstring · nullableOptional

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/sql/{connectionName}/job/{jobId}

GET /v3/sql/{connectionName}/job/{jobId} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jobId": "job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9",
  "connectionName": "carto_dw",
  "providerId": "bigquery",
  "query": "SELECT * FROM carto-demo-data.demo_tables.airports",
  "status": "success",
  "error": null,
  "createdAt": "2026-07-30T16:10:35.732Z",
  "jobMetadata": {
    "location": "US"
  },
  "metadata": {}
}

Cancel a job

delete

/v3/sql/{connectionName}/job/{jobId}

Cancels a running job. Returns no content on success.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Path parameters

connectionNamestringRequired

Name of the connection to use.

Example: carto_dw

jobIdstringRequired

The job identifier.

Example: job_h8UWzpdzX0s2XAAXQd3rdWCdPUT9

Responses

204

The job was cancelled.

No content

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

404

The resource doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

delete/v3/sql/{connectionName}/job/{jobId}

DELETE /v3/sql/{connectionName}/job/{jobId} HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List jobs

get

/v3/sql/jobs

Lists the asynchronous jobs in your account.

Only userId, createdSince and client are accepted — any other query parameter returns 400.

Authorizations

AuthorizationstringRequired

An API Access Token or an OAuth Access Token, sent as Authorization: Bearer <token>.

Query parameters

user_idstringOptional

Filter by user. Ignored when authenticating with an API Access Token, which is always scoped to its own user.

created_sincestring · date-timeOptional

Only return jobs created after this date.

Example: 2026-07-01T00:00:00.000Z

Responses

200

The jobs.

application/json

A job as returned by the list endpoint. Note this shape uses state where GET /v3/sql/{connectionName}/job/{jobId} uses status.

externalIdstringOptional

accountIdstringOptional

userIdstring · nullableOptional

connectionIdstringOptional

createdAtstring · date-timeOptional

updatedAtstring · date-timeOptional

querystring · nullableOptional

statestring · enumOptional

success, failure and cancelled are final states.

Possible values:

tokenstring · nullableOptional

400

The request is malformed or a parameter failed validation.

application/json

401

The token is missing, malformed or expired.

application/json

403

The token doesn't grant access to this resource.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/sql/jobs

GET /v3/sql/jobs HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "externalId": "text",
    "accountId": "text",
    "userId": null,
    "connectionId": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "createdAt": "2026-08-09T08:52:51.813Z",
    "updatedAt": "2026-08-09T08:52:51.813Z",
    "query": null,
    "state": "pending",
    "jobMetadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "token": null
  }
]

PreviousMaps API NextTokens API

Last updated 8 days ago

Was this helpful?

Choosing an endpoint

About queryParameters and parameterized queries

Endpoints

Run a query

Run a query (POST)

Create a job

Get a job

Cancel a job

List jobs

About `queryParameters` and parameterized queries