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
curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000"
}'
curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"resource": "transactions",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"filters": [
{
"field": "currency",
"op": "eq",
"value": "USD"
}
],
"sort_field": "created_at",
"sort_dir": "desc",
"limit": 100,
"offset": 0
}'
{
"data": {
"run_id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
"rows": [
{
"currency": "USD",
"txn_count": 1280
}
],
"total": 1,
"duration_ms": 842
}
}
{
"error": {
"code": "INVALID_REQUEST",
"message": "instance_id is required"
}
}
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.
POST /data/lake/query accepts data:read or data:write. This feature is available only to Production managed instances and Enterprise customers.Authorization
Blnk Cloud APIs support any one of the following authentication methods. All of them work with yourCLOUD_API_KEY or OAUTH_ACCESS_TOKEN.
Pass X-blnk-key: CLOUD_API_KEY or X-blnk-key: OAUTH_ACCESS_TOKEN.
Request body
You can create a new query in two ways: using SQL or using filters.curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000"
}'
curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"resource": "transactions",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"filters": [
{
"field": "currency",
"op": "eq",
"value": "USD"
}
],
"sort_field": "created_at",
"sort_dir": "desc",
"limit": 100,
"offset": 0
}'
- Using SQL
- 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.string
required
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.string
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.string
Last day of lake history Cloud opens for this query. Required with
start_date when you send sql. Must be after start_date.string
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.string
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.string
required
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.string
required
Which lake table to query. One of
transactions, balances, ledgers, or identity. Confirm column names with Get lake schema.string
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.string
Last day of lake history Cloud opens. Required if
start_date is empty. Must be after start_date when both are set.array
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.| Field | Description |
|---|---|
field | Column to filter on, such as currency or status. Must exist on resource. |
op | Comparison: eq (equal), gt, gte, lt, lte, like, or ilike (case-insensitive like) |
value | Value to compare against field |
string
Column to sort by, such as
created_at or amount. Must exist on resource.string
Sort order for
sort_field: asc (lowest first) or desc (highest first).integer
Maximum number of rows to return. Must be 0 or greater.
integer
Number of rows to skip before the first result. Use with
limit to move through results. Must be 0 or greater.Response
{
"data": {
"run_id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
"rows": [
{
"currency": "USD",
"txn_count": 1280
}
],
"total": 1,
"duration_ms": 842
}
}
{
"error": {
"code": "INVALID_REQUEST",
"message": "instance_id is required"
}
}
string
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.array
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).integer
Number of rows the query produced. Can be larger than
rows when the SQL preview is truncated.integer
How long the query took to execute, in milliseconds.
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.Was this page helpful?
⌘I
curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000"
}'
curl -X POST 'https://api.cloud.blnkfinance.com/data/lake/query' \
-H 'X-blnk-key: CLOUD_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"instance_id": "YOUR_INSTANCE_ID",
"resource": "transactions",
"start_date": "2026-08-01",
"end_date": "2026-08-31",
"filters": [
{
"field": "currency",
"op": "eq",
"value": "USD"
}
],
"sort_field": "created_at",
"sort_dir": "desc",
"limit": 100,
"offset": 0
}'
{
"data": {
"run_id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
"rows": [
{
"currency": "USD",
"txn_count": 1280
}
],
"total": 1,
"duration_ms": 842
}
}
{
"error": {
"code": "INVALID_REQUEST",
"message": "instance_id is required"
}
}