Execute Harbor Saved Query

Submits the current published Harbor saved query for asynchronous reader-only execution. Use a Harbor-bound scoped credential with query access to the Harbor's backing Connection. Administrator credentials cannot submit executions here. Saved queries require a Polytomic-managed Harbor. Polytomic selects the current published revision while processing your request. The response identifies that exact immutable revision. Selection happens before Polytomic accepts the execution. Drafts, unpublished queries, and archived queries are unavailable for selection. You cannot select a historical revision or supply SQL through this endpoint. > ⚠️ Concurrent publication changes > > Publishing, unpublishing, or archiving a saved query after selection does not > change the selected revision. An in-flight request may still be accepted and > execute that revision. Unpublishing or archiving does not cancel in-flight > requests or queued executions. Query access is checked again before execution > and result retrieval. Parameter values are bound separately from SQL. Omitted parameters use the published `default_value`, never draft validation values. An omitted optional parameter without a default binds SQL `NULL`. Required parameters allow omission when a default exists, but reject explicit `null` even with a default. Missing required values without defaults, explicit `null` for required parameters, unknown parameter names, and invalid scalar types return `422 Unprocessable Entity` without accepting an execution. Execution requires reader credentials and never falls back to writer credentials. For report windows, define parameters with `required: true` and a `default_value`, such as `7` for a `days` parameter. This allows omission while preventing explicit `null` from turning a time filter into a SQL `NULL` comparison. To archive a saved query through REST, use [`DELETE /api/harbors/{harbor_id}/saved-queries/{saved_query_id}`](../../../../../../api-reference/harbors/delete-saved-query). Unpublish is available only through the GraphQL `unpublishHarborSavedQuery` mutation, not a REST endpoint. ## Results The response returns a task ID with status `created`, not result rows. Poll [`GET /api/queries/{id}`](../../../../../../api-reference/query-runner/get-query) using a credential from the same Harbor profile. Query access is checked again before execution and result retrieval. Stop polling at `done`, `failed`, or `unknown`; `unknown` means execution started but no durable terminal result is available. Results and detailed failure information expire after 24 hours. Use the `expires` field and follow `links.next` to retrieve additional result pages. ## Harbor Activity Send a new nonzero UUID in `X-Polytomic-Activity-Request-ID`. Missing or invalid IDs return `400 Bad Request`. Reusing a consumed ID returns `409 Conflict` and does not create another execution. You may omit `X-Polytomic-Harbor-Session` for direct REST requests. If supplied, the session must be active and bound to your credential and Harbor. Polytomic records `query.submitted` atomically with acceptance. The event identifies the saved query, immutable revision, published version, and bounded name snapshot. SQL, parameter values and defaults, column names, and result rows remain outside Activity metadata. If Activity persistence is unavailable, the request returns `503 Service Unavailable` without accepting an execution. `query.started` records provider invocation. `query.succeeded` means results are available for authorized retrieval, not that you have consumed them.