---
title: "Execute Data Engine SQL query"
method: POST
path: "/api/v1/organization/data-engine/query"
tags: ["Data Engine"]
---

# Execute Data Engine SQL query

`POST /api/v1/organization/data-engine/query`

Run a read-only SQL query against the organization's data and return the resulting rows.
Results are automatically scoped to the target organization, so do not add any organization
filter yourself.

This endpoint is only available when the Data Engine feature is enabled for the server.

Use MySQL syntax for building SQL queries. Identifiers may be quoted with backticks; a reserved
word used as a column name (e.g. `value`) must be quoted this way.

Limitations:
  * Only a single read-only SELECT statement is allowed. INSERT, UPDATE, DELETE and any DDL are
    rejected. CTEs (WITH) and set operations (UNION, INTERSECT, EXCEPT) are allowed.
  * Window functions (the OVER clause) are not supported.
  * Only an allow-listed set of functions may be used; any other function is rejected:
    - Aggregates: COUNT, SUM, AVG, MIN, MAX, STDDEV, STDDEV_POP, STDDEV_SAMP, VARIANCE, VAR_POP,
      VAR_SAMP, BIT_AND, BIT_OR, BIT_XOR, ANY_VALUE, PERCENTILE_CONT, PERCENTILE_DISC.
    - Math: ABS, CEIL, CEILING, FLOOR, ROUND, TRUNCATE, MOD, POWER, SQRT, EXP, LN, LOG10, SIGN.
    - Date/time: EXTRACT, TIMESTAMPADD, TIMESTAMPDIFF, CURRENT_TIMESTAMP, CURRENT_DATE,
      CURRENT_TIME, LOCALTIMESTAMP, LOCALTIME, NOW.
    - Conditional / null handling: COALESCE, NULLIF, IFNULL.
    - String: LOWER, UPPER, TRIM, LENGTH, CHAR_LENGTH, CHARACTER_LENGTH, SUBSTRING, CONCAT,
      REPLACE.
    - Type conversion: CAST.
  * Standard query clauses (WHERE, GROUP BY, HAVING, ORDER BY, LIMIT/OFFSET), JOINs, CASE
    expressions, IN, and comparison/boolean/arithmetic operators are always allowed.
  * A query returns at most 100000 rows and must finish within 30 seconds.

The response uses a compact representation: `meta` lists the result columns in order (each entry
carries the column `name`), and `rows` holds one positional array of values per result row,
aligned by index with the columns in `meta`.

Required permissions, when user-scoped authentication is used: `QUERY_DATA_ENGINE`.

## Request body

- object
  - `sql` string, required — A single read-only SQL SELECT statement to run against the organization data.
  - `orgId` integer — Organization to run the query for. If not provided, the organization associated with the authentication token is used.

## Response `200`

Query executed successfully

- object
  - `meta` object[] — Result columns in order; each entry describes one column and is aligned by index with the values in every row array.
    - `name` string — Column name.
  - `rows` array[] — Result rows, each a positional array of column values aligned with meta.
    - unknown[]
      - unknown

## Other responses

- `400` — Bad request
- `403` — User is missing the QUERY_DATA_ENGINE permission
- `404` — Data Engine feature is disabled
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.dev/blynk/apis/blynk-platform-api.md) · [All operations](https://skmtc.dev/blynk/apis/blynk-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/blynk/blynk-platform-api/revisions/d8640cc48a13/schema)