---
title: "Run Query"
method: POST
path: "/api/connections/{connection_id}/query"
tags: ["Query Runner"]
---

# Run Query

`POST /api/connections/{connection_id}/query`

Submits a query for asynchronous execution against the connection.

This endpoint returns immediately with a query task ID. It does not wait for
the query to finish. Poll [`GET /api/queries/{id}`](../../../../api-reference/query-runner/get-query) until `status`
reaches `done` or `failed`.

Only the user who created the query can fetch its results later. Query results
are stored temporarily and may expire; use the `expires` field from the result
endpoint to understand how long they will remain available.

## Path parameters

- `connection_id` string, uuid, required — Unique identifier of the connection to run the query against.

## Query parameters

- `query` string — The query to execute against the connection.

## Headers

- `X-Polytomic-Version` string

## Request body

- RunQueryRequest
  - `query` string — The query to execute against the connection.

## Response `200`

OK

- RunQueryEnvelope
  - `data` RunQueryResult
    - `count` integer — The number of rows returned by the query. This will not be returned until the query completes.
    - `error` string — Error message if the query failed.
    - `expires` string — The time at which the query will expire and be deleted. This will not be returned until the query completes.
    - `fields` string[] — The names of the fields returned by the query. This will not be returned until the query completes.
    - `id` string, uuid — The ID of the query task. Poll GET /api/queries/{id} until the task reaches done or failed to retrieve results.
    - `results` object[] — The query results, returned as an array of objects.
    - `status` 'created' | 'running' | 'done' | 'failed'

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/polytomic/apis/polytomic-api.md) · [All operations](https://skmtc.net/polytomic/apis/polytomic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polytomic/polytomic-api/versions/b509e00e80aa/schema)