# 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 `). * See [Getting Started → Authentication](/developer-guide/getting-started/authentication.md) * See [Getting Started → Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md) ## Endpoint * Method: `POST` * Path: `/v1//admin/sql_query` * Auth: `Authorization: Bearer ` * 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. {% 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
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
Managed compute" %} ``` ## Example Request {% tabs %} {% tab title="cURL" %} ```bash curl --request POST \ --url "https:///v1//admin/sql_query" \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --data ‘{ "sql_query": "SELECT * FROM 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 `` with your region's API host (see [Getting Started → Regions & Endpoints](/developer-guide/getting-started/regions-and-endpoints.md)) and `
` 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. ```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 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: 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: ``` GET https://docs.amigo.ai/developer-guide/classic-api/data-access/sql-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.