Imports API

Import geospatial files into your data warehouse.

Imports read a file from a public URL and create a table in your data warehouse, running the checks and optimizations that make the result usable in Builder and in your own applications.

The work happens asynchronously: create a job, then poll it until status is success, failure or cancelled.

Endpoint	What it does
POST /v3/imports	Create an import job
GET /v3/imports	List import jobs
POST /v3/imports/preview	Preview an import
GET /v3/imports/{jobId}	Get an import job
POST /v3/imports/{jobId}/cancel	Cancel an import job

Each organization can run 5 import jobs concurrently. Creating a sixth while five are still pending or running returns 429.

Files are read from a public URL, and the size limit is 5 GB for all formats. Let us know if you need a higher limit.

Letting CARTO detect the schema, or setting it yourself

By default autoguessing is on and CARTO infers column types from the file. That is usually what you want.

When it guesses wrong — a postal code read as a number, a date in an unusual format — preview the import first, adjust the columns it returns, then create the job with autoguessing: false and your schema. Sending a schema while autoguessing is on has no effect.

CARTO supports importing CSV, GeoJSON, GeoPackage, KML, KMZ, TAB, Shapefiles (in a .zip package), and GeoParquet files. These formats can be imported into any connected data warehouse.

GeoTIFF raster files are also supported when importing into BigQuery, Snowflake, and Databricks connections. The resulting table follows the Raquet specification.

The size limit for file imports is 5 GB for all formats.

Endpoints

Create an import job

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/imports

Imports a geospatial file from a URL into a table in your data warehouse.

The job runs asynchronously — poll GET /v3/imports/{jobId} with the returned jobId.

By default CARTO guesses the schema of the file. To set it yourself, call POST /v3/imports/preview first, then pass autoguessing: false together with the schema you want.

Each account can run 5 import jobs concurrently.

Authorizations

accessToken

AuthorizationstringRequired

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

Body

application/json

connectionstringRequired

Name of the connection to import through.

urlstring · uriRequired

Public URL of the file to import.

destinationstringRequired

Fully qualified name of the table to create.

overwritebooleanOptional

Replace the destination table if it already exists.

Default: false

autoguessingbooleanOptional

Let CARTO detect the schema. Set to false to import with the schema you provide.

Default: true

dryRunbooleanOptional

Validate the import without writing anything. Can't be combined with overwrite.

Default: false

ignoreErrorsbooleanOptional

Skip rows that fail to parse. Defaults to the value of autoguessing.

maxErrorsintegerOptional

How many bad rows to tolerate. Defaults to 1000 when autoguessing is on, 0 otherwise.

wrapDateLinebooleanOptional

Wrap geometries that cross the antimeridian.

Default: false

preserveSourceCrsbooleanOptional

Keep the source coordinate reference system instead of reprojecting to EPSG:4326.

Default: false

Responses

201

The import job was created.

application/json

jobIdstring · uuidOptional

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

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 connection doesn't exist.

application/json

429

You already have 5 import jobs running. Wait for one to finish.

application/json

post/v3/imports

HTTPcURLJavaScriptPython

POST /v3/imports HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 152

{
  "connection": "carto_dw",
  "url": "https://libs.cartocdn.com/data/airports.geojson",
  "destination": "carto-dw-project.my_dataset.airports",
  "overwrite": false
}

{
  "jobId": "5a32a0ea-555a-48dd-aeb1-8768aae8ef1c",
  "status": "pending"
}

List import jobs

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/imports

Lists import jobs. By default only pending and running jobs are returned — pass status to widen the search.

Authorizations

accessToken

AuthorizationstringRequired

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

Query parameters

statusstringOptional

Comma-separated list of statuses to return. Defaults to pending,running.

Example: success,failure

created_sincestring · date-timeOptional

Only return jobs created after this date.

Responses

200

The import jobs.

application/json

jobIdstring · uuidOptional

createdAtstring · date-timeOptional

connectionstringOptional

resourcestringOptional

The URL the data was imported from.

destinationstringOptional

overwritebooleanOptional

Only returned by the list endpoint.

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

erroranyOptional

Empty string when the job hasn't failed. Otherwise a message or a structured error object.

401

The token is missing, malformed or expired.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/imports

HTTPcURLJavaScriptPython

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

[
  {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2026-08-09T09:05:53.391Z",
    "connection": "text",
    "resource": "text",
    "destination": "text",
    "overwrite": true,
    "status": "pending",
    "error": null,
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
]

Preview an import

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/imports/preview

Inspects a file and returns the schema CARTO would use to import it, without importing anything.

Use the returned columns as a starting point for the schema of a manual import.

Authorizations

accessToken

AuthorizationstringRequired

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

Body

application/json

connectionstringRequired

Name of the connection to import through.

urlstring · uriRequired

Public URL of the file to inspect.

Responses

201

The detected schema.

application/json

rasterbooleanOptional

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 connection doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/imports/preview

HTTPcURLJavaScriptPython

POST /v3/imports/preview HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "connection": "carto_dw",
  "url": "https://libs.cartocdn.com/data/airports.geojson"
}

{
  "columns": [
    {
      "name": "geom",
      "type": "GEOGRAPHY",
      "nullable": true
    },
    {
      "name": "name",
      "type": "STRING",
      "nullable": true
    }
  ],
  "options": [
    {
      "name": "STRING"
    },
    {
      "name": "INT64"
    },
    {
      "name": "FLOAT64"
    },
    {
      "name": "GEOGRAPHY"
    }
  ],
  "source": {
    "driver": "GeoJSON",
    "ogrSource": "airports.geojson",
    "schema": [
      {
        "name": "name",
        "type": "STRING"
      }
    ]
  }
}

Get an import job

get

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/imports/{jobId}

Returns the current state of an import job. Poll this until status is success, failure or cancelled.

Authorizations

accessToken

AuthorizationstringRequired

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

Path parameters

jobIdstring · uuidRequired

The job identifier returned when the job was created.

Responses

200

The import job.

application/json

jobIdstring · uuidOptional

createdAtstring · date-timeOptional

connectionstringOptional

resourcestringOptional

The URL the data was imported from.

destinationstringOptional

overwritebooleanOptional

Only returned by the list endpoint.

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

erroranyOptional

Empty string when the job hasn't failed. Otherwise a message or a structured error object.

401

The job belongs to another user.

application/json

404

The resource doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/imports/{jobId}

HTTPcURLJavaScriptPython

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

{
  "jobId": "5a32a0ea-555a-48dd-aeb1-8768aae8ef1c",
  "createdAt": "2026-07-30T16:10:35.732Z",
  "connection": "carto_dw",
  "resource": "https://libs.cartocdn.com/data/airports.geojson",
  "destination": "carto-dw-project.my_dataset.airports",
  "status": "success",
  "error": "",
  "metadata": {}
}

Cancel an import job

post

https://gcp-us-east1.api.carto.comhttps://gcp-europe-west1.api.carto.comhttps://gcp-asia-northeast1.api.carto.comhttps://gcp-australia-southeast1.api.carto.comhttps://your-carto-tenant-domain.com/api

/v3/imports/{jobId}/cancel

Cancels an import job that is still pending or running. Cancelling a job that already finished returns 400.

Authorizations

accessToken

AuthorizationstringRequired

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

Path parameters

jobIdstring · uuidRequired

Responses

200

The cancelled job.

application/json

jobIdstring · uuidOptional

createdAtstring · date-timeOptional

connectionstringOptional

resourcestringOptional

The URL the data was imported from.

destinationstringOptional

overwritebooleanOptional

Only returned by the list endpoint.

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

erroranyOptional

Empty string when the job hasn't failed. Otherwise a message or a structured error object.

400

The job already finished and can't be cancelled.

application/json

401

The token is missing, malformed or expired.

application/json

403

The job belongs to another user.

application/json

404

The resource doesn't exist.

application/json

429

You went over the rate limit for this API.

application/json

post/v3/imports/{jobId}/cancel

HTTPcURLJavaScriptPython

POST /v3/imports/{jobId}/cancel HTTP/1.1
Host: gcp-us-east1.api.carto.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "jobId": "5a32a0ea-555a-48dd-aeb1-8768aae8ef1c",
  "createdAt": "2026-07-30T16:10:35.732Z",
  "connection": "carto_dw",
  "resource": "https://libs.cartocdn.com/data/airports.geojson",
  "destination": "carto-dw-project.my_dataset.airports",
  "status": "cancelled",
  "error": ""
}