---
title: "Create an export job"
method: POST
path: "/v3/exports"
tags: ["Exports"]
---

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

## Request body

- ExportRequest
  - `connection` string, required — Name of the connection to export through.
  - `source` string, required — A fully qualified table name, or a SQL query when `type` is `query`. A named source is also accepted for queries.
  - `format` 'geoparquet' | 'geojson' | 'shapefile' | 'geopackage' | 'csv' | 'tab' | 'kml' | 'kmz', required
  - `type` 'table' | 'query' — Whether `source` is a table name or a query.
  - `name` string — Filename for the exported file, without extension. Defaults to the table name. Unsupported characters are replaced with `_`.
  - `destUrl` string — 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.
  - `config` object — Shape the exported rows with raw SQL fragments. Can't be combined with the structured fields below.
    - `select` string[] — Columns to export.
    - `where` string — A SQL predicate, without the leading `WHERE`.
    - `limit` integer — Maximum rows to export.
  - `columns` string[] — Columns to export. Can't be combined with `config.select`.
  - `filters` object — Attribute filters to apply.
  - `spatialFilter` object — Viewport geometry to clip to, keyed by the spatial index column.
  - `spatialDataColumn` string — The geometry or spatial index column.
  - `spatialDataType` string — `geo`, `h3`, `h3int` or `quadbin`.
  - `featureIds` string[] — Export only these features. Requires `geometryType` and `spatialDataColumn` — without both, the filter is ignored.
  - `geometryType` string — Required alongside `featureIds`.
  - `queryParameters` union — Values for the parameters in the query. A named object on BigQuery, a positional array on Snowflake, Redshift and PostgreSQL.
    - object
    - unknown[]
      - unknown

## Response `201`

The export job was created.

- object
  - `jobId` string, uuid
  - `status` 'pending' | 'running' | 'success' | 'failure' | 'cancelled' — `success`, `failure` and `cancelled` are final states.

## Other responses

- `400` — The request is malformed or a parameter failed validation.
- `401` — The token is missing, malformed or expired.
- `403` — The token doesn't grant access to this resource.
- `404` — The connection doesn't exist.
- `429` — You went over the [rate limit](#rate-limits) for this API.

---

[API](https://skmtc.net/gitbookio/apis/carto-api.md) · [All operations](https://skmtc.net/gitbookio/apis/carto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gitbookio/carto-api/revisions/019f79ecdd6c/schema)