List query runs

GET

data

lake

query-runs

curl -X GET 'https://api.cloud.blnkfinance.com/data/lake/query-runs?instance_id=YOUR_INSTANCE_ID&limit=20' \
  -H 'Authorization: Bearer CLOUD_API_KEY'

{
  "data": [
    {
      "id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
      "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
      "saved_query_id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "trigger": "manual",
      "query_name": "Applied volume by currency",
      "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
      "start_date": "2026-08-01T00:00:00Z",
      "end_date": "2026-08-31T00:00:00Z",
      "status": "succeeded",
      "row_count": 1,
      "preview_limited": false,
      "duration_ms": 842,
      "started_at": "2026-08-15T11:04:12.112739Z",
      "finished_at": "2026-08-15T11:04:12.954739Z",
      "rows": [
        {
          "currency": "USD",
          "txn_count": 1280
        }
      ]
    }
  ],
  "next_cursor": ""
}

A query run is one execution of lake SQL. Cloud creates a run when you create a new query with sql or saved_query_id, or when a scheduled saved query fires. Each run stores a snapshot of the SQL and date range that actually ran, the status of that execution, and a preview of the result rows. The preview is bounded: at most 1000 rows, or less if the preview exceeds 2 MB. It is not the full result set. Editing a saved query later does not change past runs. This endpoint returns recent runs for one instance, newest first. Use the query parameters to narrow by saved query, status, or how the run started.

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.

Query parameters

curl -X GET 'https://api.cloud.blnkfinance.com/data/lake/query-runs?instance_id=YOUR_INSTANCE_ID&limit=20' \
  -H 'Authorization: Bearer CLOUD_API_KEY'

string

required

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

string

Return only runs that came from this saved query (lake_query_...). Omit it to include every run on the instance, including ad-hoc SQL that was not saved.

string

Return only runs in this state: running (still executing), succeeded (finished with rows or an empty result), or failed (the SQL did not complete).

string

Return only runs started this way: manual (you called Create new query) or scheduled (a saved-query schedule fired).

string

ID of the last run from the previous response (next_cursor). Cloud returns the next page after that run. Omit it on the first request.

integer

Maximum number of runs to return. Defaults to 50. Maximum 100. Values outside that range are treated as 50.

Response

{
  "data": [
    {
      "id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
      "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
      "saved_query_id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "trigger": "manual",
      "query_name": "Applied volume by currency",
      "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
      "start_date": "2026-08-01T00:00:00Z",
      "end_date": "2026-08-31T00:00:00Z",
      "status": "succeeded",
      "row_count": 1,
      "preview_limited": false,
      "duration_ms": 842,
      "started_at": "2026-08-15T11:04:12.112739Z",
      "finished_at": "2026-08-15T11:04:12.954739Z",
      "rows": [
        {
          "currency": "USD",
          "txn_count": 1280
        }
      ]
    }
  ],
  "next_cursor": ""
}

array

Query runs for this instance, newest first.

Show Run properties

string

Unique id of this run (lake_query_run_...). Pass it to Get query run.

string

Unique id of the instance (instance_...).

string

Saved query this run came from (lake_query_...). Omitted when you ran ad-hoc SQL without a saved query.

string

How the run started: manual (Create new query) or scheduled (a saved-query schedule).

string

Display name of the saved query at the time of the run. Empty for ad-hoc SQL.

string

Exact SQL Cloud executed. This is a snapshot. Later edits to a saved query do not change it.

timestamp

First day of lake history this run opened. For a rolling saved query, this is the start Cloud resolved at run time.

timestamp

Last day of lake history this run opened. For a rolling saved query, this is the end Cloud resolved at run time.

string

running while Cloud is still executing, succeeded when it finished, or failed when the SQL did not complete.

integer

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

boolean

true when rows is a truncated preview (more than 1000 rows, or the preview exceeded the size cap). Use row_count for the full total.

integer

How long the query took to execute, in milliseconds.

string

Machine-readable failure code, such as INVALID_SQL or QUERY_TOO_EXPENSIVE. Present only when status is failed.

string

Human-readable reason the run failed. Present only when status is failed.

timestamp

When Cloud started executing this run.

timestamp

When the run reached succeeded or failed. Omitted while status is running.

array

Preview of result rows. Column names match the SQL aliases. At most 1000 rows. Not the full result when preview_limited is true.

string

ID of the last run on this page. Pass it as cursor on the next request to continue. Empty when there are no more runs.

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 GET 'https://api.cloud.blnkfinance.com/data/lake/query-runs?instance_id=YOUR_INSTANCE_ID&limit=20' \
  -H 'Authorization: Bearer CLOUD_API_KEY'

{
  "data": [
    {
      "id": "lake_query_run_c5d9e2a1-7b4f-4a3c-9e8d-1f6a2b4c8d30",
      "instance_id": "instance_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
      "saved_query_id": "lake_query_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
      "trigger": "manual",
      "query_name": "Applied volume by currency",
      "sql": "SELECT currency, COUNT(*) AS txn_count FROM transactions GROUP BY currency LIMIT 1000",
      "start_date": "2026-08-01T00:00:00Z",
      "end_date": "2026-08-31T00:00:00Z",
      "status": "succeeded",
      "row_count": 1,
      "preview_limited": false,
      "duration_ms": 842,
      "started_at": "2026-08-15T11:04:12.112739Z",
      "finished_at": "2026-08-15T11:04:12.954739Z",
      "rows": [
        {
          "currency": "USD",
          "txn_count": 1280
        }
      ]
    }
  ],
  "next_cursor": ""
}

Start Here

Deployments

Proxy & data

Data lake

AI integrations

Audit

Alerts

Billing

Authorization

Query parameters

Response

Need help?

​Authorization

​Query parameters

​Response

​Need help?

Authorization

Query parameters

Response

Need help?