Preview query

POST

https://apps.sarvam.ai/api/analytics/v1/:org_id/:workspace_id/query-preview

POST

/api/analytics/v1/:org_id/:workspace_id/query-preview

import requests
url = "https://apps.sarvam.ai/api/analytics/v1/org_id/workspace_id/query-preview"
payload = {
    "sql": "SELECT language_name, count() AS calls
FROM EngagementFactsBoardsView
WHERE effective_datetime >= {{start_date}}
GROUP BY language_name
ORDER BY calls DESC",
    "filter_values": { "start_date": {
            "filter_type": "date",
            "value": "2026-09-01"
        } },
    "row_limit": 100
}
headers = {
    "X-API-Key": "<your-api-key>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "columns": [
    {
      "name": "language_name",
      "type": "LowCardinality(String)"
    },
    {
      "name": "calls",
      "type": "UInt64"
    }
  ],
  "rows": [
    [
      "Hindi",
      1842
    ],
    [
      "English",
      1109
    ],
    [
      "Tamil",
      402
    ]
  ],
  "row_count": 3,
  "truncated": false,
  "execution_ms": 96
}

Executes read-only SQL against the workspace’s analytics views and returns the rows. Use it to develop a query before creating a widget from it. Safe and side-effect free despite being a POST: the SQL and filter values are too large and too structured for a query string. Tenant scoping is enforced server-side and cannot be bypassed.

Path parameters

org_idstringRequired

Organization ID

workspace_idstringRequired

Workspace ID

Request

This endpoint expects an object.

sqlstringRequired>=1 character

Read-only SELECT; same filter-token syntax as widget SQL

filter_valuesmap from strings to objectsOptional

Values for the tokens in sql, keyed by token name

row_limitintegerOptional1-10000Defaults to 1000

Maximum rows returned. Optional — omit it for the default of 1000. A LIMIT inside your SQL can narrow the result further but never widens it past this. The result reports truncated when this cut the result short.

Response

Successful Response

columnslist of objects

Column metadata in result order; position N describes position N of every row

rowslist of lists of any

Row values as positional arrays aligned 1:1 with columns, not keyed objects

row_countinteger

Number of rows in rows, which is not the total matched when truncated

truncatedboolean

True when the result was cut short by row_limit

execution_msinteger

Query execution time in milliseconds, excluding network transfer

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

408

Request Timeout Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error

Path parameters

Headers

Request

Response

Errors