---
title: "Query external tables"
method: POST
path: "/query"
tags: ["query"]
---

# Query external tables

`POST /query`

Executes one read-only SELECT against the authenticated tenant's materialized external tables. Call /query/schema first to discover logical table and column names. Authorization is tenant-wide in Phase 1; principal-level row authorization is not applied.
Required scope: `external_data:query`

## Request body

- ExternalTableQueryRequest
  - `sql` string, required — A single read-only SELECT using logical table names

## Response `200`

Bounded local/canary result, or state-only idempotent replay

- union
  - ExternalTableQueryResponse
    - `columns` string[], required
    - `rows` object[], required
    - `row_count` integer, required
    - `truncated` boolean, required
  - ExternalQueryResultResponse
    - `response_type` 'result', required
    - `request_id` string, uuid, required
    - `state` 'SUCCEEDED', required
    - `columns` ExternalQueryColumn[], required
      - `name` string, required
      - `type` string, required
    - `rows` object[], required
    - `row_count` integer, required
    - `truncated` boolean, required
  - ExternalQueryStateOnlyResponse
    - `response_type` 'state_only', required
    - `request_id` string, uuid, required
    - `state` 'RECEIVED' | 'PREPARING' | 'CACHE_READY' | 'RUNNING' | 'CANCELLING' | 'CANCELLED' | 'SUCCEEDED' | 'FAILED' | 'UNKNOWN', required
    - `terminal` boolean, required
    - `failure_class` 'invalid_request' | 'unauthorized' | 'snapshot_unavailable' | 'capacity' | 'build_timeout' | 'query_timeout' | 'internal', nullable
    - `retry_after_seconds` integer, nullable

## Other responses

- `202` — Cache preparation started without executing SQL
- `400` — Invalid or disallowed SQL
- `401` — Unauthorized
- `409` — Logical request ID conflicts with a different request body
- `422` — Request validation failed
- `429` — Actor query rate limit was exceeded; retry after the window
- `503` — Published snapshot is unavailable, or the service is unavailable

## Changes

> 63 revisions in range; 10 not diffed.

- **2026-07-26** `67d44efb04be` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/qlonolink/apis/qaip-apis/changes/query/post.md)

---

[API](https://skmtc.dev/qlonolink/apis/qaip-apis.md) · [All operations](https://skmtc.dev/qlonolink/apis/qaip-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qlonolink/qaip-apis/revisions/20ecde5da7dd/schema)