Interact with your tables and data inside CARTO, as if you were running SQL statements.
This component is still under support but it will not be further developed. We don’t recommend starting new projects with it as it will eventually become deprecated. Instead, learn more about our new APIs here
CARTO’s SQL API allows you to interact with your tables and data inside CARTO, as if you were running SQL statements against a normal database.
You can execute single SQL statements or even a batch of long-running ones. Refer to the SQL API guide to learn more.
In order to access SQL API you must provide an API key. The CARTO Authorization guide explains how these keys are sent (TLDR: HTTP basic auth or query string param with the API key token). Depending on the permissions granted to the provided API key, the request will be authorized or not.
Runs a single SQL statement using the GET endpoint:
NOTICE: If the database detects an error when it's already streaming data the status code will be 200. Make sure to check if the optional error property is set in the response.
Authorizations: |
| q required | string (SQL statement) SQL statement |
| filename | string Output filename |
| format | string (Output format) Enum:"GPKG" "CSV" "SHP" "SVG" "KML" "SpatiaLite" "GeoJSON" Output format |
Ok (Check if error property is present)
Bad Request
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
You are over platform's limits.
curl -X GET \
https://username.carto.com/api/v2/sql?q=SELECT count(*) FROM cities
Runs a single SQL statement using the POST endpoint:
Offers the same functionality as the GET endpoint. This version may come handy when dealing with complex/long statments.
NOTICE: If the database detects an error when it's already streaming data the status code will be 200. Make sure to check if the optional error property is set in the response.
Authorizations: |
| q required | string (SQL statement) |
| filename | string Output filename |
| format | string (Output format) Enum:"GPKG" "CSV" "SHP" "SVG" "KML" "SpatiaLite" "GeoJSON" Output format |
Ok (Check if error property is present)
Bad Request
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
You are over platform's limits.
Creates a Batch Queries Job
Authorizations: |
| query required | string or string or object long-running SQL statement(s). |
Ok
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
You are over platform's limits.
Returns a Batch Queries Job based on it's ID.
Authorizations: |
| job_id required | string <uuid> the job universally unique identifier (uuid). |
Ok
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
The specified resource was not found
You are over platform's limits.
curl -X GET \
https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
Updates the query of a Batch Queries Job.
Notice: Only the query property can be updated
Authorizations: |
| job_id required | string <uuid> the job universally unique identifier (uuid). |
| query required | string or string or object long-running SQL statement(s). |
Ok
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
The specified resource was not found
You are over platform's limits.
Canceles a Batch Queries Job based on it's ID. The Job doesn't get deleted, just it's status is set as canceled. Only jobs whose status are pending or running can be canceled.
Authorizations: |
| job_id required | string <uuid> the job universally unique identifier (uuid). |
Ok
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
The specified resource was not found
You are over platform's limits.
curl -X DELETE \
https://username.carto.com/api/v2/sql/job/de305d54-75b4-431b-adb2-eb6b9e546014
Runs a single COPY command:
Authorizations: |
| q required | string (SQL statement) Example: "COPY upload_example (the_geom,name,age) FROM stdin WITH (FORMAT csv,HEADER true)" COPY statement |
| Transfer-Encoding required | string Enum:"chunked" |
| Content-Encoding | string Enum:"gzip" |
Ok
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
You are over platform's limits.
curl -X POST -H 'Content-Encoding: gzip' -H 'Transfer-Encoding: chunked' -H 'Content-Type: application/octet-stream' --data-binary @upload_example.csv.gz 'https://{username}.carto.com/api/v2/sql/copyfrom?q=COPY upload_example (the_geom,name,age) FROM stdin WITH (FORMAT csv,HEADER true)&api_key={api_key}'
Runs a single COPY command:
Authorizations: |
| q required | string (SQL statement) COPY statement |
| filename | string Sets the content-disposition file name header |
Ok.
Unauthorized. No authentication provided.
Forbidden. The API key does not authorize this request.
You are over platform's limits.
curl --output upload_example_dl.csv --compressed "https://{username}.carto.com/api/v2/sql/copyto?q=COPY upload_example (the_geom,name,age) TO stdout WITH(FORMAT csv,HEADER true)&api_key={api_key}"