> This page is for version 2025-09-18 (default). > For other versions, use one of these documentation indexes: > - 2025-09-18 (default): https://apidocs.polytomic.com/2025-09-18/llms.txt > - 2024-02-08: https://apidocs.polytomic.com/2024-02-08/llms.txt > - 2023-04-25: https://apidocs.polytomic.com/2023-04-25/llms.txt > - 2022-12-12: https://apidocs.polytomic.com/2022-12-12/llms.txt > - 2021-05-23: https://apidocs.polytomic.com/2021-05-23/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://apidocs.polytomic.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.polytomic.com/_mcp/server. # Run Query POST https://app.polytomic.com/api/connections/{connection_id}/query Content-Type: application/json 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`, `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. Reference: https://apidocs.polytomic.com/api-reference/query-runner/run-query ## Authentication - `Authorization` header (bearer token, required) — Bearer user API key - `Authorization` header (basic auth, required) — Basic organization-scoped API key ## Request ### Path parameters - `connection_id` (string, required) — Unique identifier of the connection to run the query against. ### Query parameters - `query` (string, optional) — The query to execute against the connection. ### Headers - `X-Polytomic-Harbor-Session` (string, optional) - `X-Polytomic-Activity-Request-ID` (string, optional) ## Response ### 200 OK - `data` (RunQueryResult, optional) ## Errors ### 400 Bad Request Error Bad Request - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 403 Forbidden Error Forbidden - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 404 Not Found Error Not Found - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 409 Conflict Error Conflict - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 500 Internal Server Error Internal Server Error - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ### 503 Service Unavailable Error Service Unavailable - `key` (string, optional) - `message` (string, optional) - `metadata` (map from string to any, optional) - `status` (integer, optional) ## Types ### RunQueryResult - `count` (long, optional) — The number of rows returned by the query. This will not be returned until the query completes. - `error` (string, optional) — Error message if the query failed. - `expires` (string, optional) — The time at which the query will expire and be deleted. This will not be returned until the query completes. - `fields` (list of string, optional) — The names of the fields returned by the query. This will not be returned until the query completes. - `id` (string, optional) — The ID of the query task. Poll GET /api/queries/\{id} until the task reaches the terminal status done, failed, or unknown. - `results` (list of map from string to any, optional) — The query results, returned as an array of objects. - `status` (enum, optional) - Allowed values: `created`, `running`, `unknown`, `done`, `failed` ## Examples **Request** ```json {} ``` **Response** ```json { "data": { "count": 10, "error": "string", "expires": "2021-01-01T00:00:00Z", "fields": [ "name", "age" ], "id": "43d893ef-322b-47da-badb-3cf10d13a556", "results": [ {} ], "status": "created" } } ``` **SDK Code** ```python import requests url = "https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query" payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://app.polytomic.com/api/connections/248df4b7-aa70-47b8-a036-33ac447e668d/query")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```