---
title: "Create a job"
method: POST
path: "/v3/sql/{connectionName}/job"
tags: ["SQL"]
---

# Create a job

`POST /v3/sql/{connectionName}/job`

Runs a query asynchronously. Use this for queries that would exceed the
1 minute timeout of the synchronous endpoints.

Available for BigQuery, Snowflake, Redshift, PostgreSQL and CARTO Data
Warehouse connections.

Poll `GET /v3/sql/{connectionName}/job/{jobId}` with the
returned `externalId` to follow the execution.

## Path parameters

- `connectionName` string, required

## Request body

- object
  - `query` string, required — The SQL query, or the name of a named source. Note this field is `query`, not `q`.
  - `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
  - `metadata` object — Arbitrary metadata stored with the job.

## Response `200`

The job was created.

- JobCreated — An asynchronous SQL job, as returned when it is created.
  - `externalId` string — Use this to poll the job.
  - `accountId` string
  - `userId` string, nullable
  - `connectionId` string
  - `connectionName` string
  - `providerId` string
  - `metadata` object
  - `createdAt` string, date-time
  - `query` string
  - `jobMetadata` object — Provider metadata. For workflows executed via API this holds `workflowOutputTableName`.
  - `token` string, nullable

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