Run a structured query

Executes read-only SQL against explicitly selected accessible sources. Use GET /v1/sources/{sourceId}?includeFields=false to list tables, then tableId to inspect one table. Warehouse-backed sources use DuckDB SQL and can be queried together. Live remote database connectors use their native dialect (GoogleSQL for BigQuery and PostgreSQL for Supabase), must be queried one at a time, and cannot be combined with other sources. timings separates source validation, DuckDB startup, source loading, and SQL execution; totalMs excludes network transit and response serialization.

POST/v1/queries

betaauthenticatedworkspace

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. Use DuckDB SQL for warehouse-backed sources and the native dialect for one live remote connector. timings separates validation, initialization, source loading, and SQL execution; totalMs excludes network transit and response serialization. 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,
    "timings": {
      "sourceValidationMs": 2,
      "initializationMs": 5,
      "sourceLoadMs": 8,
      "sqlExecutionMs": 3,
      "totalMs": 19
    }
  }
}