---
title: "Create SQL Query"
method: POST
path: "/sql"
tags: ["SQL Queries"]
---

# Create SQL Query

`POST /sql`

## Request

- Base URL: `https://api.us-e1.tago.io`
- URL: `https://api.us-e1.tago.io/sql`
- Auth: API key in header `Profile-Token`
- TypeScript: <https://skmtc.dev/tago/apis/tagoio-api/docs/sql/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a saved TagoSQL query on your profile. The query is parsed and validated against your plan at save time and snapshotted as version 1. Enforces the saved-query count (`sql_query`) and parameter count (`sql_query_params`) plan caps. Server-owned fields (`id`, `profile`, `cache_version`, `version`, `versions`, `created_at`, `updated_at`) are never accepted from the request body. The request body cap is 64 KiB.

## Request body

- object
  - `name` string, required: Required, 1..=64 chars.
  - `description` string: Optional, <=1024 chars.
  - `query` string, required: Required. Read-only TagoSQL, validated against your plan at save time.
  - `params` object[]: Positional parameter defaults as `{ key: "$n", value: "..." }` objects. Must cover exactly the placeholders the query uses (`$1..$N`, contiguous). Values are strings. The legacy object-map form (`{ "$1": "30" }`) is rejected with a 400.
    - `key` string
    - `value` string
  - `cache_enabled` boolean: Enables the result cache on execute. Default false.
  - `cache_ttl_seconds` integer: Clamped to 0..=86400 (24h). A TTL of 0 disables caching regardless of `cache_enabled`.
  - `rate_limit_rpm` integer: Optional, >=1. Per-query soft rate cap, clamped down to the plan's `rpm_sql_execute` hard cap. Rejected at save time if it exceeds the hard cap.
  - `active` boolean: Default true. An inactive query cannot be executed.
  - `tags` object[]
    - `key` string
    - `value` string

## Response `200`

Saved query created (snapshotted as version 1).

- object
  - `status` boolean
  - `result` object
    - `id` string
    - `name` string
    - `version` integer
    - `cache_version` integer
    - `session_context` boolean: True when the query uses a session function; derived from the query text.

## Other responses

- `400`: SQL syntax or validation error, invalid params, or object-map params.
- `402`: Plan limit exceeded (saved-query count or parameter count).

## Changes

- **2026-11-07** `1a281f04cdab`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tago/apis/tagoio-api/changes/sql/post.md)

---

[API](https://skmtc.dev/tago/apis/tagoio-api.md) - [All operations](https://skmtc.dev/tago/apis/tagoio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tago/apis/tagoio-api/revisions/1a281f04cdab?raw)