CARTO API Reference

Reference for the CARTO API

The CARTO API lets you work with data in your data warehouse through an existing connection in your CARTO organization.

Authorization

Every request needs a bearer token:

Authorization: Bearer <YOUR_TOKEN>

There are two kinds of token:

• API Access Token — grants access to specific sources through a specific connection. Use it in public applications. Works with the Maps, SQL, Imports and LDS APIs. Create one in the Workspace.

• OAuth Access Token — represents a user. Works with every API, and is the only option for the Tokens, Named Sources, Resources and Activity Data APIs.

To get an OAuth Access Token, create an OAuth Client in the Developers section of your Workspace and exchange its credentials:

curl --request POST \
  --url 'https://auth.carto.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials' \
  --data 'client_id=<YOUR_CLIENT_ID>' \
  --data 'client_secret=<YOUR_CLIENT_SECRET>' \
  --data 'audience=carto-cloud-native-api'

API Base URL

Each CARTO Cloud region and Self-Hosted tenant has its own base URL. Use the one for your organization — you can copy it from the Developers section of the Workspace.

Region	API Base URL
United States East	https://gcp-us-east1.api.carto.com
Europe West	https://gcp-europe-west1.api.carto.com
Asia Northeast	https://gcp-asia-northeast1.api.carto.com
Australia Southeast	https://gcp-australia-southeast1.api.carto.com

Rate limits

CARTO Cloud is protected by a web application firewall that temporarily blocks any IP going over these limits:

API	Requests per minute
Maps	3500
SQL	2500
LDS	3000
Imports	500
Tokens	300
Connections	100

Requests answered by the CDN cache don't count towards the limit. Going over it returns a 429 response.

New to the CARTO API? Start with How to make my first API call.

The APIs

Maps API

Map layers from queries, tables and tilesets

SQL API

Run queries, synchronously or as jobs

Tokens API

Create and manage API Access Tokens

Imports API

Import geospatial files into your data warehouse

LDS API

Geocoding, isolines and routing

Named Sources API

Server-side aliases for SQL queries

Resources API

Manage maps, workflows and connections

Activity Data API

Export activity and API usage data