---
title: "Run Harbor Query"
method: POST
path: "/api/harbors/{harbor_id}/query"
tags: ["Harbors"]
---

# Run Harbor Query

`POST /api/harbors/{harbor_id}/query`

## Request

- Base URL: `https://app.polytomic.com`
- URL: `https://app.polytomic.com/api/harbors/{harbor_id}/query`
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Submits a query against the Harbor backing connection for asynchronous execution.

Use a scoped credential bound to this Harbor. The query runs only against the
Harbor's backing connection; you cannot select another connection on this route.
Send a unique `X-Polytomic-Activity-Request-ID` UUID with each submission. The
`X-Polytomic-Harbor-Session` header is optional; if you send one, it must be
valid for this Harbor.

The response contains a query ID and an initial `created` status. Poll
[`GET /api/queries/{id}`](../../../../api-reference/query-runner/get-query) with that ID
until the status is `done`, `failed`, or `unknown`. Follow the result endpoint's
pagination links for additional rows. Results are temporary; check `expires`
on the completed query.

## Path parameters

- `harbor_id` string, uuid, required: Unique identifier of the Harbor whose backing connection runs the query

## Headers

- `X-Polytomic-Version` string
- `X-Polytomic-Harbor-Session` string: Harbor session token; when supplied, the session must be active and bound to this credential and Harbor.
- `X-Polytomic-Activity-Request-ID` string: New nonzero UUID for each request, required for scoped credentials; a reused value is rejected.

## Request body

- RunHarborQueryRequest
  - `query` string, required: SQL query to execute against the Harbor backing 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 the terminal status done, failed, or unknown.
    - `results` object[]: The query results, returned as an array of objects
    - `status` 'created' | 'running' | 'unknown' | 'done' | 'failed'

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-22** `d80b0fdea14e`: 1 breaking, 7 warning, 1 info
  - the `data` response's property type changed from `object` to no type for status `200`
  - removed the optional property `data/count` from the response with the `200` status
  - removed the optional property `data/error` from the response with the `200` status
  - removed the optional property `data/expires` from the response with the `200` status
  - …5 more
- **2026-10-21** `61c2b96f65ba`: 1 breaking, 6 info
  - the `data/status` response's property type changed from `string` to no type for status `200`
  - added `#/components/schemas/QueryStatus` to the `data/status` response property `allOf` list for the response status `200`
  - removed the `created` enum value from the `data/status` response property for the response status `200`
  - removed the `done` enum value from the `data/status` response property for the response status `200`
  - …3 more
- **2026-09-30** `46a7ef9927b4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/polytomic/apis/polytomic-api/changes/api/harbors/:harbor_id/query/post.md)

---

[API](https://skmtc.dev/polytomic/apis/polytomic-api.md) - [All operations](https://skmtc.dev/polytomic/apis/polytomic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/polytomic/apis/polytomic-api/revisions/3c88180d2470?raw)