> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-developers/reference/carto-api/sql-api.md).

# SQL API

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](/carto-user-manual/workflows/executing-workflows-via-api.md) 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**.

{% hint style="success" %}

## **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.

{% code overflow="wrap" %}

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

{% endcode %}

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

**Snowflake**

Snowflake supports positional parameters, such as:

{% code overflow="wrap" %}

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

{% endcode %}

**Redshift and PostgreSQL**

Snowflake supports positional parameters, such as:

{% code overflow="wrap" %}

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

{% endcode %}
{% endhint %}

## Endpoints

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/{connectionName}/query" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/{connectionName}/query" method="post" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/{connectionName}/job" method="post" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/{connectionName}/job/{jobId}" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/{connectionName}/job/{jobId}" method="delete" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/sql/jobs" method="get" %}
<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>
{% endopenapi %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-developers/reference/carto-api/sql-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.