# SQL API (Serverless)

Run read-only SQL queries against your organization’s data over HTTPS. Queries execute on serverless compute managed by Amigo; you do not need to provision or operate any infrastructure.

## Access & Permissions

* Feature must be enabled for your organization by Amigo (request via Slack).
* Beta: The SQL API is in active development; behavior and limits may change.
* Endpoint requires elevated privileges; use an admin or service account token per your internal security policy.
* Standard Amigo authentication applies (Authorization: Bearer ).
  * See: [Getting Started → Authentication](https://docs.amigo.ai/developer-guide/getting-started/authentication)
  * See: [Getting Started → Regions & Endpoints](https://docs.amigo.ai/developer-guide/getting-started/regions-and-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): Currently only `false` is supported for synchronous queries.

{% hint style="warning" %}
Only `SELECT` is allowed. DDL/DML and administrative statements are rejected.
{% endhint %}

## Query Execution Flow

{% @mermaid/diagram content="%%{init: {"theme": "base", "themeVariables": {"actorBkg": "#083241", "actorTextColor": "#FFFFFF", "actorBorder": "#083241", "signalColor": "#575452", "signalTextColor": "#100F0F", "labelBoxBkgColor": "#F1EAE7", "labelBoxBorderColor": "#D7D2D0", "labelTextColor": "#100F0F", "loopTextColor": "#100F0F", "noteBkgColor": "#F1EAE7", "noteBorderColor": "#D7D2D0", "noteTextColor": "#100F0F", "activationBkgColor": "#E8E2EB", "activationBorderColor": "#083241", "altSectionBkgColor": "#F1EAE7", "altSectionColor": "#100F0F"}}}%%
sequenceDiagram
autonumber
participant Client as Your System
participant API as SQL API
participant Engine as Serverless Query Engine
participant Data as Organization Tables

```
Client->>API: POST /admin/sql_query
Note over Client,API: SELECT statement<br/>async_query: false
API->>Engine: Execute Query
Engine->>Data: Read Tables
Data-->>Engine: Result Set (max 1000 rows)
Engine-->>API: Query Results
API-->>Client: JSON Response

Note over Engine: No infrastructure to manage<br/>Managed compute" %}
```

## Example Request

{% tabs %}
{% tab title="cURL" %}

```bash
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
  }’
```

{% endtab %}

{% tab title="Python SDK" %}

```python
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["rows"]:
        print(row)
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
// 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.rows.forEach((row: any) => console.log(row));
```

{% endtab %}
{% endtabs %}

Replace `<REGIONAL-BASE-URL>` with your region’s API host (see [Getting Started → Regions & Endpoints](https://docs.amigo.ai/developer-guide/getting-started/regions-and-endpoints)) and `<TABLE>` with a table available to your organization.

## Response

On success, the response contains execution metadata, columns, and rows. For synchronous queries, at most 1000 rows are returned per request.

```json
{
  "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 returned for synchronous requests.
* Timeout: 30 seconds per synchronous query.
* Rate limiting: 6 requests per minute per user.

{% hint style="info" %}
If you need to extract larger result sets or run recurring analytics jobs, use Delta Sharing.
{% endhint %}

## 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/URL, authentication method, and any required parameters).
* Configure your client/tool using the provided details and your admin/service account credentials or token.

{% hint style="info" %}
Because environments vary, always use the exact connection information Amigo provides for your tenant. Do not guess driver names, ports, or parameters.
{% endhint %}