Data lake

The data lake gives you SQL access (using the ClickHouse SQL dialect) to a queryable replica of your nullplatform organization's data. This includes audit events plus the current state of your applications, scopes, deployments, parameters, and other resources, all through a single endpoint.

Use it to build custom reports, investigate incidents, or feed data into external dashboards and BI tools.

🧪 Early preview

The data lake is in early preview. Table schemas and query behavior may change as the product evolves.

Prerequisites

To use the Data Lake API, you need an API key with one of these roles: Admin, SecOps, Dev, DevOps, or Insight Viewer. All roles are scoped by NRN, so query results are limited to the resources your token can access. See API keys to create one and Roles for role details.

Execute a query

Send a POST request to https://api.nullplatform.com/data/lake/query with your SQL statement.

You can send the SQL in three ways:

JSON body

curl -X POST 'https://api.nullplatform.com/data/lake/query' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{ "query": "SELECT * FROM audit_events LIMIT 10" }'

Plain text body

curl -X POST 'https://api.nullplatform.com/data/lake/query' \
  -H 'Content-Type: text/plain' \
  -H 'Authorization: Bearer <token>' \
  -d 'SELECT * FROM audit_events LIMIT 10'

Query string parameter

curl -X POST 'https://api.nullplatform.com/data/lake/query?query=SELECT%20*%20FROM%20audit_events%20LIMIT%2010' \
  -H 'Authorization: Bearer <token>'

The response streams directly from the data lake. By default, results come back in tab-separated format. To get JSON, add a FORMAT JSON clause to your SQL:

SELECT * FROM audit_events LIMIT 10 FORMAT JSON

Parametrized queries

You can use ClickHouse parametrized queries by passing param_ prefixed query string parameters:

curl -X POST 'https://api.nullplatform.com/data/lake/query?param_user_id=42' \
  -H 'Content-Type: text/plain' \
  -H 'Authorization: Bearer <token>' \
  -d 'SELECT * FROM audit_events WHERE user_id = {user_id:Int64} FORMAT JSON'

Parameters are passed directly to ClickHouse, so you can use any supported ClickHouse type in the placeholder.

SQL restrictions

The API enforces strict validation to keep queries safe:

Rule	Detail
Read-only	Only SELECT, WITH, SHOW, DESCRIBE, DESC, and EXPLAIN statements are allowed
Single statement	Each request must contain exactly one SQL statement
Max length	Queries can't exceed 50,000 characters
Query timeout	Queries must complete within 30 seconds

Queries that violate the read-only, single-statement, or length rules return a 400 Invalid SQL error. Queries that exceed the timeout are aborted and return a 409 query execution error.

note

The API also blocks SQL functions that reach external data sources, such as remote, url, file, s3, mysql, and postgresql. Queries that use any of these return a 403 Forbidden SQL error.

NRN-based access control

Your query results are automatically scoped to the resources your token has access to. The API resolves your token's NRN grants and passes them as a session filter to the data lake.

For example, if your token grants access to organization=1:account=2, you'll only see audit events for that account and everything below it (namespaces, applications, scopes).

The filtering is hierarchical: a grant at the organization level includes all descendant resources. Redundant grants (like organization=1 and organization=1:account=2) are automatically deduplicated, keeping only the broadest scope.

Rate limiting

The API enforces a rate limit of 60 requests per minute per authentication token. If you exceed this limit, you'll receive a 429 Too Many Requests response with retry timing headers.

There is no hard cap on result size. In practice, queries are bounded by the 30-second timeout and the rate limit above.

Error responses

Status	Code	Description
400	FST_ERR_INVALID_SQL	SQL validation failed (not read-only, multiple statements, or exceeds max length)
401	FST_ERR_AUTHENTICATION	Missing or invalid bearer token
403	FST_ERR_AUTHORIZATION	Token has no granted resources for governance:lake:read
403	FST_ERR_FORBIDDEN_SQL	Query matches an AST restriction pattern
409	FST_ERR_CLICKHOUSE_QUERY	ClickHouse returned an error while executing the query
429	Too Many Requests	Rate limit exceeded

All errors return a JSON body:

{
  "statusCode": 400,
  "code": "FST_ERR_INVALID_SQL",
  "error": "Bad Request",
  "message": "SQL query must be read-only"
}

Next steps

• Table reference: browse all tables organized by domain, with column schemas and relationships.
• Connect with a database client: set up a connection from DBeaver, DataGrip, or other JDBC-compatible tools.