---
title: "List recent queries for the calling tenant"
method: GET
path: "/v1/query/history"
tags: ["query"]
---

# List recent queries for the calling tenant

`GET /v1/query/history`

## Request

- Base URL: `https://data.thinair.co`
- URL: `https://data.thinair.co/v1/query/history`
- Auth: API key in header `x-api-key`

Read the tenant's per-tenant query log — recent SQL with timing, row counts, error status, and the tool that emitted each entry. The ring buffer holds up to 100 entries with a 7-day TTL. **Free to call** — never debits quota and never returns 429 (a quota-exhausted user must still be able to inspect their own activity).

## Query parameters

- `limit` integer: Max entries to return (1–100). Default 20.
- `connection` string: Filter to entries on this connection. Matches the entry's `connectionId` (uuid) — pass the connection id, not its display name. Optional.
- `since_iso` string, date-time: Drop entries older than this ISO 8601 timestamp. Useful for `?since=last_check` polling. Optional.

## Response `200`

Query history (newest-first).

- QueryHistoryResponse: Per-tenant query log. Free observability call — does not debit quota and never returns 429.
  - `entries` QueryHistoryEntry[], required: Recent queries newest-first. Capped at the per-tenant ring-buffer size (100). Entries older than 7 days are dropped by the retention policy — long-term audit lives elsewhere.
    - `id` string, required: Stable per-entry id (UUID v4).
    - `connection_id` string, required: Connection id the query targeted (NOT the human display name).
    - `sql` string, required: Original SQL — may be truncated to a redacted summary (≤ 200 chars + ellipsis when longer). The MCP `query_history` tool applies the same truncation; the limit keeps history payloads bounded.
    - `execution_ms` integer, required
    - `row_count` integer, required
    - `tool` string, required: Tool that emitted the entry — `query_sql` for raw user queries, `explain_query` / `optimize_query` / etc. for the architect-tier tools.
    - `timestamp` string, date-time, required: Wall-clock at write time, ISO 8601 (UTC).
    - `tables` string[], required: Tables referenced by the SQL (best-effort parse at write time).
    - `error` string, nullable, required: Translated error message when the query failed; `null` on success. Failed queries are still logged so a tenant can see what didn't work.
  - `meta` QueryHistoryMeta, required
    - `count` integer, required: Number of entries returned (post-filter).
    - `applied_limit` integer, required: Effective `limit` after clamping.
    - `connection` string: Echo of the `connection` filter when the caller passed one.
    - `since_iso` string: Echo of the `since_iso` cutoff when the caller passed one.

## Other responses

- `400`: Invalid query parameters (out-of-range `limit`, malformed `since_iso`).
- `401`: Authentication required or failed.

---

[API](https://skmtc.dev/thinair/apis/thinair-data-api.md) · [All operations](https://skmtc.dev/thinair/apis/thinair-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thinair/apis/thinair-data-api/revisions/8a2a2d1b2400?raw)