Open Dashboard

This feature is only available in the Enterprise version

Data lake

Create new query

Learn what the instance data lake is and run read-only SQL against it through Blnk Cloud.

POST/data/lake/query

The data lake is a stored copy of your ledger, built for reports. Your ledger stays the system of record. A lake builder then copies ledgers, balances, transactions, and identities into daily history for reporting and audits.

This endpoint runs read-only SQL against that copy. It is not a live instance query. Use it for reporting and audits over a date range. The start_date and end_date you send choose which days of history Cloud opens. A WHERE filter can drop rows inside those days. It does not choose which days to scan.

When you send sql or saved_query_id, Cloud also records a query run: one execution, with a snapshot of the SQL and dates plus a result preview. Filter-mode requests return rows in this response and do not create a run.

For current holdings, use the Ledger API. To learn more about the data lake, see Insights.

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.

Request body

You can create a new query in two ways: using SQL or using filters.

Send a read-only SELECT or WITH statement. Narrow rows in the SQL with WHERE. To rerun a saved query, send saved_query_id instead of sql.

instance_idstringrequiredbody

Unique id of the instance (instance_...). Get it from get instance details. Do not pass deployment_id. Optional when you send saved_query_id; Cloud uses the saved query’s instance.

Pass it in the request JSON, not as a query parameter.

start_datestringbody

First day of lake history Cloud opens for this query. ISO date (2026-08-01) or datetime. Required with end_date when you send sql. A WHERE clause can drop rows inside these days. It does not choose which days to scan.

end_datestringbody

Last day of lake history Cloud opens for this query. Required with start_date when you send sql. Must be after start_date.

sqlstringbody

One read-only DuckDB SELECT or WITH statement. Cloud infers tables from the SQL. Allowed tables are transactions, balances, ledgers, identity, and anomalies. Do not send sql together with saved_query_id or resource.

saved_query_idstringbody

ID of a saved query to run (lake_query_...) instead of sending sql. Cloud loads the saved SQL and resolves the date range from the query’s range_mode (fixed dates or the current rolling window).

Query one ledger resource with structured filters instead of SQL. Send resource and omit sql and saved_query_id.

instance_idstringrequiredbody

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

Pass it in the request JSON, not as a query parameter.

resourcestringrequiredbody

Which lake table to query. One of transactions, balances, ledgers, or identity. Confirm column names with Get lake schema.

start_datestringbody

First day of lake history Cloud opens. ISO date (2026-08-01) or datetime. Required if end_date is empty. Filters only drop rows inside these days. They do not choose which days to scan.

end_datestringbody

Last day of lake history Cloud opens. Required if start_date is empty. Must be after start_date when both are set.

filtersarraybody

Conditions to apply on top of the date range. Omit filters to return rows from resource with no extra conditions. Each object needs field, op, and value.

FieldDescription
fieldColumn to filter on, such as currency or status. Must exist on resource.
opComparison: eq (equal), gt, gte, lt, lte, like, or ilike (case-insensitive like)
valueValue to compare against field
sort_fieldstringbody

Column to sort by, such as created_at or amount. Must exist on resource.

sort_dirstringbody

Sort order for sort_field: asc (lowest first) or desc (highest first).

limitintegerbody

Maximum number of rows to return. Must be 0 or greater.

offsetintegerbody

Number of rows to skip before the first result. Use with limit to move through results. Must be 0 or greater.

Response

run_idstring

ID of the query run Cloud recorded for this SQL request (lake_query_run_...). Use it to fetch the snapshot and preview later. Present when you send sql or saved_query_id.

rowsarray

Result rows for this request. Column names match the SQL aliases, or the columns of resource when you used filters. For SQL, this is the same bounded preview stored on the query run (at most 1000 rows).

totalinteger

Number of rows the query produced. Can be larger than rows when the SQL preview is truncated.

duration_msinteger

How long the query took to execute, in milliseconds.