Run a structured query – POST /v1/queries

POST/v1/queries

betaapiKeyworkspace

When to use

Run read-only SQL when you already know the exact table names and source IDs.

For agents

Use after source inspection for exact rows. For natural-language questions, start an answer job first.

Example

typescript

import { PermuteClient } from '@permute/sdk';

const orgClient = new PermuteClient({
  apiKey: process.env.PERMUTE_API_KEY!,
});

const client = orgClient.withWorkspace(process.env.PERMUTE_WORKSPACE_ID!);

const result = await client.query({
  "sourceIds": [
    "data_abc123",
    "conn_hubspot123"
  ],
  "sql": "SELECT * FROM \"blok_revenue\" LIMIT 10",
  "limit": 100
});

Request body

json

{
  "sourceIds": [
    "data_abc123",
    "conn_hubspot123"
  ],
  "sql": "SELECT * FROM \"blok_revenue\" LIMIT 10",
  "limit": 100
}

Response

json

{
  "data": {
    "queryId": "qry_abc123",
    "sourceIds": [
      "data_abc123",
      "conn_hubspot123"
    ],
    "sql": "SELECT * FROM \"blok_revenue\" LIMIT 10",
    "columns": [
      {
        "name": "month"
      },
      {
        "name": "revenue"
      }
    ],
    "rows": [
      {
        "month": "2026-03",
        "revenue": 120000
      }
    ],
    "rowCount": 1,
    "truncated": false,
    "executionMs": 18
  }
}