Skip to navigation
API ReferenceQuery Runner

Run 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} until status reaches done, failed, or unknown. These statuses are terminal.

A Harbor-bound scoped credential can submit freeform SQL only against its Harbor’s backing connection, even if its profile allows other connections. Other credentials retain their existing connection access. Query results are stored temporarily and may expire; use the expires field from the result endpoint to understand how long they remain available.

Authentication

AuthorizationBearer
Bearer user API key
OR
AuthorizationBasic

Basic organization-scoped API key

Path parameters

connection_idstringRequiredformat: "uuid"
Unique identifier of the connection to run the query against

Headers

X-Polytomic-VersionstringOptional
X-Polytomic-Harbor-SessionstringOptional

Harbor session token; when supplied, the session must be active and bound to this credential and Harbor.

X-Polytomic-Activity-Request-IDstringOptional

New nonzero UUID for each request, required for scoped credentials; a reused value is rejected.

Query parameters

querystringOptional
The query to execute against the connection

Request

This endpoint expects an object.

Response

OK
dataobjectOptional
The submitted query

Errors

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