The /run_sql endpoint executes SQL queries against your database and returns the results as structured data. This endpoint can be used to run SQL queries generated by the /generate_sql endpoint or custom SQL queries you've written.

Basic Usage

// Request
{
  "projectId": 1,
  "sql": "SELECT * FROM \"olist_customers_dataset\" LIMIT 10"
}

// Response
{
  "id": "09d46224-0068-4ca3-bce4-f1fc85093eb6",
  "records": [
    {
      "customer_id": "00012a2ce6f8dcda20d059ce98491703",
      "customer_unique_id": "248ffe10d632bebe4f7267f1f44844c9",
      "customer_zip_code_prefix": "06273",
      "customer_city": "osasco",
      "customer_state": "SP"
    },
    {
      "customer_id": "000161a058600d5901f007fab4c27140",
      "customer_unique_id": "b0015e09bb4b6e47c52844fab5fb6638",
      "customer_zip_code_prefix": "35550",
      "customer_city": "itapecerica",
      "customer_state": "MG"
    },
    "... additional records ..."
  ],
  "columns": [
    {
      "name": "customer_id",
      "type": "VARCHAR"
    },
    {
      "name": "customer_unique_id",
      "type": "VARCHAR"
    },
    {
      "name": "customer_zip_code_prefix",
      "type": "VARCHAR"
    },
    {
      "name": "customer_city",
      "type": "VARCHAR"
    },
    {
      "name": "customer_state",
      "type": "VARCHAR"
    }
  ],
  "threadId": "503a8ca5-8171-43b5-b45b-86de2849467b",
  "totalRows": 10
}

Error Handling

{
  "id": "6fb82c31-a40d-4b8e-9e5f-c1d8a742db76",
  "code": "DATABASE_ERROR",
  "error": "Error executing SQL: Table 'nonexistent_table' doesn't exist"
}

Error codes may include:

DATABASE_ERROR: An error occurred while executing the SQL query
INVALID_SQL: The SQL syntax is invalid
NO_DEPLOYMENT_FOUND: No active database connection was found

Workflow Example

Generate SQL using the /generate_sql endpoint
Pass the generated SQL to /run_sql to execute and get results
Optionally use the same threadId in follow-up queries to maintain context

200Successfully executed SQL

400Bad request or SQL execution error

401Unauthorized

403Forbidden - Project access denied