> 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/exports-api.md).

# Exports API

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](/carto-for-developers/reference/carto-api/named-sources-api.md).

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.

{% hint style="warning" %}
`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.
{% endhint %}

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

{% openapi src="<https://openapi.gitbook.com/o/zP3LT2Qhlb5jPWQCfWV3/spec/carto-api>" path="/v3/exports" 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/exports" 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/exports/{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/exports/{jobId}/cancel" method="post" %}
<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/exports-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.