Open Dashboard

This feature is only available in the Enterprise version

Data lake

Create saved query

Save a lake SQL query with a fixed or rolling date range.

POST/data/lake/queries

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.

Enterprise authentication

Send these requests to https://api.cloud.blnkfinance.com on Blnk Cloud. On a self-hosted Enterprise deployment, send them to ENTERPRISE_PUBLIC_URL.

Pass an Enterprise API key, or an OAuth access token, in the X-blnk-key header. Create the key in Enterprise API keys, or issue a token with Enterprise OAuth.

This credential comes from the Cloud or Enterprise workspace. A Core API key belongs to the Core instance.

X-blnk-keystringrequiredheader

Enterprise API key, or an OAuth access token.

Body

instance_idstringrequiredbody

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

namestringrequiredbody

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

descriptionstringbody

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

sqlstringrequiredbody

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.

range_modestringrequiredbody

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.

start_datestringbody

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

end_datestringbody

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

rolling_daysintegerbody

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

idstring

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

instance_idstring

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

owner_user_idstring

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

namestring

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

descriptionstring

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

sqlstring

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

range_modestring

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

start_datetimestamp

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

end_datetimestamp

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

rolling_daysinteger

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

created_attimestamp

When Cloud created this saved query.

updated_attimestamp

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