TAtago
SQL Queries

Execute SQL Query

Changed on

Run a saved query. Every body field is optional: a bare POST with an empty body runs the saved query with its stored defaults and the cache enabled. Applies a per-query soft rate cap (rate_limit_rpm, clamped to the plan's hard cap) checked before the per-profile hard cap (rpm_sql_execute); cache hits are charged against a separate cached-read ceiling (rpm_sql_execute_cached).

Authentication accepts either a Profile Token (runs the query directly as its owning profile) or an Access-Management-granted analysis / Run-user token (the token must be granted the execute action on the query by id or tag; the query then runs as its owning profile). The grant authorizes execution, not filtering.

If the query uses session functions (session_user_id, session_user_tag), those values are resolved from the executing user's session at run time, after authorization and before the cache lookup: a Run user gets their own values, the profile owner gets the query's COALESCE fallbacks (a session function with no fallback is a 400), and an analysis is rejected with a 400. A resolved value that matches nothing returns empty data (zero rows, 200), never the fallback.

post/sql/{sqlID}/execute

Request

Path parameters

sqlIDstring required
Example:6a1b2c3d4e5f6a1b2c3d4e5f

The saved query ID.

Request body

testboolean

Runs a probe that skips the cache entirely (no read, no write) and always returns served_from_cache: false. Not a limit bypass: both rate-limit buckets are still consumed.

after_devicestring

Keyset cursor for device_data_by_tag fan-out queries: resume the device set strictly after this device id (with ORDER BY device). Each page caches independently. Ignored by non-fan-out queries.

Example request

{
  "params": [
    {
      "key": "$1",
      "value": "40"
    }
  ],
  "after_device": "62a1b3c4d5e6f7a8b9c0d1e2"
}

Response

Query result envelope.

statusboolean

Example response

{
  "status": true,
  "result": {
    "columns": [
      {
        "name": "variable",
        "type": "string"
      }
    ],
    "row_count": 1,
    "execution_ms": 12
  }
}

Changes