---
title: "Query Data"
method: POST
path: "/api/data/tables/query"
tags: ["data"]
---

# Query Data

`POST /api/data/tables/query`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/data/tables/query`
- Auth: HTTP bearer

Route a data action for an agent's dataset.

Actions:
- ``list_tables``: return all tables registered for the agent
- ``sample``: return N sample rows from a table (requires ``body.table``)
- ``query``: execute a SQL statement (requires ``body.sql``)
- ``save``: execute SQL and save result as a new Parquet table (requires ``body.sql`` + ``body.name``)
- ``register_source``: create a bare DataTable record (requires ``body.name`` + ``body.backend``)

## Request body

- DataQueryRequest
  - `agent_id` string, uuid, required
  - `action` string, required: query | list_tables | sample | register_source | save
  - `sql` string, nullable
  - `table` string, nullable
  - `name` string, nullable
  - `limit` integer
  - `backend` string, nullable
  - `config` object, nullable
  - `credential_id` string, uuid, nullable
  - `conversation_id` string, uuid, nullable

## Response `200`

Successful Response

- DataQueryResponse
  - `success` boolean, required
  - `columns` string[]
  - `rows` array[]
    - unknown[]
      - unknown
  - `row_count` integer
  - `total_available` integer
  - `truncated` boolean
  - `execution_ms` integer
  - `backend` string, nullable
  - `async_dispatched` boolean
  - `message` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)