SQL API (Serverless)

Run read-only SQL queries against organization tables over HTTPS with serverless compute.

Run read-only SQL queries against your organization's data over HTTPS. Queries execute on serverless compute managed by Amigo, so you don't need to provision or operate any infrastructure.

Access and Permissions

The feature must be enabled for your organization by Amigo (request via Slack).
Beta: the SQL API is in active development, so behavior and limits may change.
The endpoint requires elevated privileges; use an admin or service account token per your internal security policy.
Standard Amigo authentication applies (Authorization: Bearer <token>).
- See Getting Started → Authentication
- See Getting Started → Regions & Endpoints

Endpoint

Method: POST
Path: /v1/<YOUR-ORG-ID>/admin/sql_query
Auth: Authorization: Bearer <AUTH-TOKEN-OF-USER>
Content-Type: application/json

Request Body

sql_query (string): a read-only SELECT statement over your data.
async_query (boolean): only false is supported today, for synchronous queries.

Only SELECT is allowed. DDL, DML, and administrative statements are rejected.

Query Execution Flow

Example Request

curl --request POST \
  --url "https://<REGIONAL-BASE-URL>/v1/<YOUR-ORG-ID>/admin/sql_query" \
  --header "Authorization: Bearer <AUTH-TOKEN-OF-USER>" \
  --header "Content-Type: application/json" \
  --data '{
    "sql_query": "SELECT * FROM <TABLE> LIMIT 10",
    "async_query": false
  }'

from amigo_sdk import AmigoClient

# SQL API is not yet in the SDK resource layer.
with AmigoClient() as client:
    resp = client._http.request(
        "POST",
        f"/v1/{client.config.organization_id}/admin/sql_query",
        json={
            "sql_query": "SELECT * FROM conversation LIMIT 10",
            "async_query": False,
        },
    )
    result = resp.json()
    print(f"Execution time: {result['execution_time_ms']}ms")
    for row in result["result"]:
        print(row)

// SQL API is not yet in the SDK resource layer.
const response = await fetch(
  `${baseUrl}/v1/${orgId}/admin/sql_query`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sql_query: "SELECT * FROM conversation LIMIT 10",
      async_query: false,
    }),
  }
);
const result = await response.json();
console.log(`Execution time: ${result.execution_time_ms}ms`);
result.result.forEach((row: any) => console.log(row));

Replace <REGIONAL-BASE-URL> with your region's API host (see Getting Started → Regions & Endpoints) and <TABLE> with a table available to your organization.

Response

On success, the response contains execution metadata, columns, and rows. Synchronous queries return at most 1000 rows per request.

{
  "execution_time_ms": 1234,
  "truncated": false,
  "columns": [
    { "name": "id", "type": "STRING" },
    { "name": "created_at", "type": "TIMESTAMP" }
  ],
  "result": [
    ["a1b2c3", "2025-01-20T12:34:56Z"],
    ["d4e5f6", "2025-01-21T08:15:42Z"]
  ]
}

Limits and Behavior

Read-only: SELECT statements only. DDL, DML, and admin commands are not allowed.
Result size: up to 1000 rows per synchronous request.
Timeout: 30 seconds per synchronous query.
Rate limiting: 6 requests per minute per user.

If you need to extract larger result sets or run recurring analytics jobs, use Delta Sharing.

JDBC/ODBC Connectivity (Optional)

If you plan to connect BI tools or ETL platforms via standard database drivers:

Private preview: JDBC/ODBC connectivity is available only to select customers.
Request consideration by messaging your Amigo representative via Slack. Availability is limited and not guaranteed for all tenants.
You will receive driver and connection details (host or URL, authentication method, and any required parameters).
Configure your client or tool using the details provided, along with your admin or service account credentials.

Environments vary, so always use the exact connection information Amigo provides for your tenant. Don't guess driver names, ports, or parameters.

PreviousData Access NextDelta Sharing

Last updated 5 days ago

Was this helpful?