Exports API

Export tables and query results to a file.

Exports take a table or a query in your data warehouse and write it out as a file — GeoParquet, GeoJSON, CSV, a Shapefile and more. Use it to hand data to a system that doesn't speak SQL, to snapshot a filtered view, or to move results out of CARTO entirely.

The work happens asynchronously: create a job, poll it until status is success, then download the file.

Endpoint	What it does
POST /v3/exports	Create an export job
GET /v3/exports	List export jobs
GET /v3/exports/{jobId}	Get an export job
POST /v3/exports/{jobId}/cancel	Cancel an export job

Where the file goes

By default the export lands in CARTO's storage and the finished job carries a signed result.downloadUrl, valid for 24 hours. That is the simplest path: create, poll, download.

Pass destUrl to write directly to your own bucket instead — gs://, s3:// or https://. The job then reports outputUrl and no downloadUrl, since you already control where the file lives. Use this when the export feeds a pipeline rather than a person.

Choosing what to export

source is a table name by default. Pass type: query to export the result of a SQL query instead, or the name of a named source.

To narrow what comes out, use either raw SQL fragments or the structured fields — not both:

• config.select, config.where and config.limit take SQL directly. Straightforward when you are writing the query yourself.

• columns, filters, spatialFilter, featureIds and their companions describe the same thing structurally, and are what Builder sends.

Mixing the two returns 400. config.limit is the exception — it works alongside either.

featureIds needs both geometryType and spatialDataColumn. Without them the filter is silently dropped and you get the whole table, so the API rejects the request rather than exporting more than you asked for.

Formats

geoparquet, geojson, shapefile, geopackage, csv, tab, kml and kmz.

GeoParquet is the best default for large exports — it is compact, typed and reads back into any warehouse. Shapefiles are capped at 2 GB by the format itself, so large datasets fail rather than truncate.

Cancelling

A 200 from the cancel endpoint doesn't guarantee the job stopped. If it finished while your request was in flight, the response carries its real final status instead. Read status rather than trusting the status code.

Endpoints

Create an export job

post

/v3/exports

Exports a table or a query to a file.

The job runs asynchronously — poll it until status is success, then download the file from result.downloadUrl.

By default the file lands in CARTO's storage and the job returns a signed download URL valid for 24 hours. Pass destUrl to write to your own bucket instead, in which case no download URL is returned.

Authorizations

AuthorizationstringRequired

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

Body

connectionstringRequired

Name of the connection to export through.

sourcestringRequired

A fully qualified table name, or a SQL query when type is query. A named source is also accepted for queries.

formatstring · enumRequiredPossible values:

typestring · enumOptional

Whether source is a table name or a query.

Default: tablePossible values:

namestringOptional

Filename for the exported file, without extension. Defaults to the table name. Unsupported characters are replaced with _.

destUrlstringOptional

Write the export to your own bucket instead of CARTO's storage. Accepts gs://, s3:// and https://. When set, the job returns no download URL.

columnsstring[]Optional

Columns to export. Can't be combined with config.select.

spatialDataColumnstringOptional

The geometry or spatial index column.

spatialDataTypestringOptional

geo, h3, h3int or quadbin.

featureIdsstring[]Optional

Export only these features. Requires geometryType and spatialDataColumn — without both, the filter is ignored.

geometryTypestringOptional

Required alongside featureIds.

queryParametersone ofOptional

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

or

Responses

201

The export 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 went over the rate limit for this API.

application/json

post/v3/exports

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

{
  "connection": "carto_dw",
  "source": "carto-demo-data.demo_tables.airports",
  "format": "geoparquet"
}

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

List export jobs

get

/v3/exports

Lists your organization's export jobs, newest first.

Authorizations

AuthorizationstringRequired

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

Query parameters

limitintegerOptional

How many jobs to return.

Default: 50

offsetintegerOptional

How many jobs to skip.

Default: 0

Responses

200

The export jobs.

application/json

jobIdstring · uuidOptional

createdAtstring · date-timeOptional

connectionstringOptional

Name of the connection. Falls back to its identifier if the connection has since been deleted.

sourcestringOptional

formatstring · enumOptionalPossible values:

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

errorstringOptional

Empty string when the job hasn't failed.

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/exports

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

[
  {
    "jobId": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "connection": "text",
    "source": "text",
    "format": "geoparquet",
    "status": "pending",
    "error": "text",
    "result": {
      "rowCount": 1,
      "format": "text",
      "outputUrl": "text",
      "downloadUrl": "text",
      "fileSize": 1,
      "expirationDate": "2026-01-01T00:00:00.000Z"
    }
  }
]

Get an export job

get

/v3/exports/{jobId}

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

Authorizations

AuthorizationstringRequired

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

Path parameters

jobIdstring · uuidRequired

The export job identifier.

Example: 5a32a0ea-555a-48dd-aeb1-8768aae8ef1c

Responses

200

The export job.

application/json

jobIdstring · uuidOptional

createdAtstring · date-timeOptional

connectionstringOptional

Name of the connection. Falls back to its identifier if the connection has since been deleted.

sourcestringOptional

formatstring · enumOptionalPossible values:

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

errorstringOptional

Empty string when the job hasn't failed.

401

The token is missing, malformed or expired.

application/json

404

The job doesn't exist, or belongs to another organization.

application/json

429

You went over the rate limit for this API.

application/json

get/v3/exports/{jobId}

GET /v3/exports/{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-31T16:10:35.732Z",
  "connection": "carto_dw",
  "source": "carto-demo-data.demo_tables.airports",
  "format": "geoparquet",
  "status": "success",
  "error": "",
  "result": {
    "rowCount": 1000,
    "format": "geoparquet",
    "outputUrl": "gs://carto-exports/exports/5a32a0ea-555a-48dd-aeb1-8768aae8ef1c/airports.parquet",
    "downloadUrl": "https://storage.googleapis.com/carto-exports/exports/5a32a0ea-555a-48dd-aeb1-8768aae8ef1c/airports.parquet?X-Goog-Signature=...",
    "fileSize": 70307,
    "expirationDate": "2026-08-01T16:10:35.732Z"
  }
}

Cancel an export job

post

/v3/exports/{jobId}/cancel

Cancels an export job that is still pending or running.

A 200 doesn't guarantee the job was cancelled — if it finished while the request was in flight, the response carries its actual final status. Always read status rather than relying on the status code.

Authorizations

AuthorizationstringRequired

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

Path parameters

jobIdstring · uuidRequired

The export job identifier.

Example: 5a32a0ea-555a-48dd-aeb1-8768aae8ef1c

Responses

200

The job's status after the attempt — cancelled, or the state it reached first.

application/json

jobIdstring · uuidOptional

statusstring · enumOptional

success, failure and cancelled are final states.

Possible values:

400

The job already finished and can't be cancelled.

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

429

You went over the rate limit for this API.

application/json

post/v3/exports/{jobId}/cancel

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

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