Create saved query

POST

data

lake

queries

curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/queries' \
  -H 'Authorization: Bearer CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01",
    "end_date": "2026-08-31"
  }'

{
  "data": {
    "id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "owner_user_id": "user_01K4EX0BRXHNNGCRVT2TPNK07W",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T00:00:00Z",
    "rolling_days": 0,
    "created_at": "2026-08-12T09:28:16.864765Z",
    "updated_at": "2026-08-12T09:28:16.864765Z"
  }
}

{
  "error": {
    "code": "INVALID_SQL",
    "message": "sql is required"
  }
}

A saved query is lake SQL you store on an instance so you can rerun it later. It is not a query run. Saving does not execute the SQL. After you save it, run it with Create new query by sending saved_query_id, or attaching a schedule.

A saved query stores SQL only. You cannot create one with resource and filters, and you cannot update an existing saved query to filters later. Use Create new query when you want to query with filters.

Authorization

Blnk Cloud APIs support any one of the following authentication methods. All of them work with your CLOUD_API_KEY or OAUTH_ACCESS_TOKEN.

Bearer token
X-Blnk-Key header
X-API-Key header

Pass Authorization: Bearer CLOUD_API_KEY or Authorization: Bearer OAUTH_ACCESS_TOKEN.

string

required

Cloud API key or OAuth access token. Create credentials in API keys or OAuth.

Pass X-Blnk-Key: CLOUD_API_KEY or X-Blnk-Key: OAUTH_ACCESS_TOKEN.

string

required

Cloud API key or OAuth access token. Create credentials in API keys or OAuth.

Pass X-API-Key: CLOUD_API_KEY or X-API-Key: OAUTH_ACCESS_TOKEN.

string

required

Cloud API key or OAuth access token. Create credentials in API keys or OAuth.

Body

curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/queries' \
  -H 'Authorization: Bearer CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01",
    "end_date": "2026-08-31"
  }'

string

required

Unique id of the instance (instance_...). Get it from get instance details. Do not pass deployment_id.

string

required

Label shown in Insights and copied onto query runs that come from this query. Maximum 160 characters.

string

Optional note about what the query returns. Maximum 1000 characters.

string

required

One read-only DuckDB SELECT or WITH statement Cloud will run each time you execute this query. Same table and statement rules as Create new query.

string

required

How Cloud picks the lake date range when the query runs. fixed uses start_date and end_date on every run. rolling uses the last rolling_days days, resolved at run time.

string

First day of lake history. Required when range_mode is fixed. ISO date (2026-08-01) or datetime. Omit it for rolling queries.

string

Last day of lake history. Required when range_mode is fixed. Must be after start_date. Omit it for rolling queries.

integer

Required when range_mode is rolling. Number of days of lake history Cloud opens when the query runs (1 to 3650). Cloud resolves the window at run time: UTC for a manual run, or the schedule timezone when a schedule fires.For example, 30 opens the last 30 days. A manual run on 16 September 2026 (UTC) opens 2026-08-18 through 2026-09-16. Omit it for fixed queries.

Response

{
  "data": {
    "id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "owner_user_id": "user_01K4EX0BRXHNNGCRVT2TPNK07W",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T00:00:00Z",
    "rolling_days": 0,
    "created_at": "2026-08-12T09:28:16.864765Z",
    "updated_at": "2026-08-12T09:28:16.864765Z"
  }
}

{
  "error": {
    "code": "INVALID_SQL",
    "message": "sql is required"
  }
}

string

Unique id of this saved query (lake_query_...). Pass it as saved_query_id on Create new query.

string

Unique id of the instance (instance_...) this query is bound to.

string

User who created the query. Anyone in the workspace can run it. Only this owner or an admin can update, delete, or schedule it.

string

Label shown in Insights and copied onto query runs that come from this query.

string

Note you sent about what the query returns, or an empty string if you omitted it.

string

Read-only DuckDB SELECT or WITH Cloud stored. Cloud runs this statement each time you execute the query.

string

How Cloud picks the lake date range when the query runs: fixed or rolling.

timestamp

First day of lake history for a fixed query. Omitted when range_mode is rolling.

timestamp

Last day of lake history for a fixed query. Omitted when range_mode is rolling.

integer

Number of days of lake history to open when range_mode is rolling. 0 when the query is fixed.

timestamp

When Cloud created this saved query.

timestamp

When the saved SQL, name, description, or date range was last changed. Same as created_at on a new query.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/queries' \
  -H 'Authorization: Bearer CLOUD_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "instance_id": "YOUR_INSTANCE_ID",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01",
    "end_date": "2026-08-31"
  }'

{
  "data": {
    "id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
    "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "owner_user_id": "user_01K4EX0BRXHNNGCRVT2TPNK07W",
    "name": "Applied volume by currency",
    "description": "APPLIED transaction counts by currency",
    "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
    "range_mode": "fixed",
    "start_date": "2026-08-01T00:00:00Z",
    "end_date": "2026-08-31T00:00:00Z",
    "rolling_days": 0,
    "created_at": "2026-08-12T09:28:16.864765Z",
    "updated_at": "2026-08-12T09:28:16.864765Z"
  }
}

{
  "error": {
    "code": "INVALID_SQL",
    "message": "sql is required"
  }
}

Start Here

Deployments

Proxy & data

Data lake

AI integrations

Audit

Alerts

Billing

Authorization

Body

Response

Need help?

​Authorization

​Body

​Response

​Need help?

Authorization

Body

Response

Need help?