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 Concurrence, so you don't need to provision or operate any infrastructure.

Access and Permissions

• The feature must be enabled for your organization by Concurrence (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 Concurrence authentication applies (Authorization: Bearer <token>).

  • See Getting Started → Authentication
  • See Getting Started → Regions & Endpoints

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.

Submit a SQL query

post

/v1/{organization}/admin/sql_query

Execute a read-only SQL query on Amigo's databases for the specified organization.

Permissions

This endpoint requires the authenticated user to have greater privileges than the DefaultAdministratorRole.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-namestring · nullableOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

sql_querystring · min: 1Required

The SQL query to execute.

async_querybooleanRequired

Whether the query is asynchronous. If true, a signed URL will be returned to download the results once the query is complete. If false, the results will be returned in the response, but at most 1000 rows will be returned, and the query is subject to a 30 second execution timeout.

Responses

200

Succeeded.

application/json

execution_time_msintegerRequired

The time taken to execute the query in milliseconds.

truncatedbooleanRequired

Whether the result was truncated due to the row limit.

400

This endpoint is not supported in the current environment, or the SQL query is invalid.

401

Invalid authorization credentials.

403

Missing required permissions.

404

The specified organization does not exist.

408

The supplied query cannot be executed within the time limit.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 6 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post/v1/{organization}/admin/sql_query

POST /v1/{organization}/admin/sql_query HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "sql_query": "text",
  "async_query": true
}

{
  "execution_time_ms": 1,
  "result": [
    []
  ],
  "truncated": true,
  "columns": [
    {
      "name": "text",
      "type": "text"
    }
  ]
}

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

Query Execution Flow

Example Request

cURL

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
  }'

Python SDK

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)

TypeScript SDK

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

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 Concurrence 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 Concurrence provides for your tenant. Don't guess driver names, ports, or parameters.