> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/data-access/sql-api.md).

# SQL API (Serverless)

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](/developer-guide/getting-started/authentication.md)
  * See [Getting Started → Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md)

## Endpoint Reference

The embedded contract defines the authenticated request body and response schema. The current implementation accepts read-only `SELECT` statements and supports only synchronous execution with `async_query: false`.

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/admin/sql\_query" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

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

## Query Execution Flow

```mermaid
%%{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["result"]:
        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.result.forEach((row: any) => console.log(row));
```

{% endtab %}
{% endtabs %}

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

## 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.

{% 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 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.

{% hint style="info" %}
Environments vary, so always use the exact connection information Amigo provides for your tenant. Don't guess driver names, ports, or parameters.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/data-access/sql-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.