Cluvio API (v2024-06-01)
Welcome to the Cluvio public API!
The Cluvio public API can be used to programmatically view and manage your organization's Cluvio account from your own backend application. By using the Cluvio API, you can integrate the functionality of Cluvio into your organization's software stack to further automate your Cluvio-driven business analystics.
Security
The Cluvio public API is an HTTP API with Transport Layer Security. Individual requests are authenticated via API keys, which are described in more detail below.
JSON
All data transmitted in requests and responses on the Cluvio API is encoded in
JSON. The request and response bodies of most
create-read-update operations furthermore adhere to the structure defined by
JSON:API. Whether a request or response body uses a
JSON:API or regular JSON structure is identified in this documentation in the
request body schema and response schema definitions of each API operation,
respectively. The MIME type
application/json
identifies plain JSON and application/vnd.api+json
identifies
JSON according to JSON:API. These MIME types are transmitted in the Accept
and Content-Type
HTTP headers.
⚠ Any JSON attributes in API responses which are not documented must not be relied upon. Such attributes are not part of the public API and may disappear or be renamed without notice.
Clients
At this time, there are no programming-language-specific clients provided by Cluvio for the Cluvio API. It is easy to get started with the Cluvio API from any programming language by using your preferred HTTP client library. For ad hoc experimentation, command-line tools like curl can be used.
The Cluvio API uses two types of servers, API Servers and Data Servers.
The Cluvio servers are available in both of Cluvio's deployment locations, namely the US and the EU. When using the Cluvio API it is important to use the Cluvio servers corresponding to your Cluvio account location. You can see your Cluvio account location in the organization's admin settings.
Most Cluvio API operations are provided by the API servers and thus grouped as
API Server Operations
on the left-hand side navigation. API server operations
require an API key for request authorization that has the permissions
required for the operation. Each operation lists the required API key permissions.
In contrast, operations that fetch schema data or query result data must be
performed on Cluvio data servers. These are grouped as Data Server Operations
on the left-hand side navigation and require a short-lived data access
token for request authorization. Data access tokens
are obtained from certain API server operations.
EU Servers
- API server: https://api.eu.cluvio.com/
- Data server: https://data.eu.cluvio.com/
US Servers
- API server: https://api.us.cluvio.com/
- Data server: https://data.us.cluvio.com/
An API key grants access to the API server operations. API keys can be created, updated and deleted by any admin in your organization. See API Keys in the Cluvio admin settings for details on managing API keys.
Usage
Each API key has a secret token, sometimes just referred to as the API key's secret. This secret is used to authenticate requests on the Cluvio API by including it in the request's Authorization header as follows:
Authorization: Api <secret>
The custom authentication
scheme
Api
identifies the following secret to be an API key secret. The placeholder <secret>
is to be
replaced with your API key secret.
API key secrets do not expire and are valid for use on the Cluvio API for as long as the API key exists and is enabled.
Permissions
An API key has a set of permissions and some permissions may be restricted to
specific resources, like datasources. In the documentation of an API operation,
the AUTHORIZATIONS
section lists the permissions required for the
operation. For example,
AUTHORIZATIONS:
ApiKey (Manage Datasources)
indicates that the API key must have the Manage Datasources
permission to
perform the operation.
A data access token is a short-lived token that grants access to a data server operation. It may be obtained in the response of an API server operation and is always provided together with a data key. The data key together with the data access token uniquely identify the data to fetch from a Cluvio data server.
Usage
To use a data access token, include it in the request's Authorization header as follows:
Authorization: Data <token>
The custom authentication
scheme
Data
identifies the following text to be a data access token. The placeholder <token>
is to be replaced with the token obtained from the Cluvio API server.
Note: It is important to issue the data server request against the same Cluvio server location as
the API server request that was used to obtain the data access token. For example, if you issued
an API request to api.eu.cluvio.com
and received a data key and data access token,
the request to fetch the data must be sent to data.eu.cluvio.com
.
Data access tokens expire within minutes. When received in a response from a Cluvio API server, they must be used immediately on a Cluvio data server, if the client wants to fetch the associated data.
The following is a list of changes made to this API version since the initial release, in chronological order.
July 31st 2024
The values
and value_names
attributes are now available in the
Create Filter and
Update Filter operations
to create and update drop-down filters with manual / static options.
Use the Get Drop-Down Filter
Options operation to fetch the
options for an existing drop-down filter.
July 18th 2024
The include
query parameter is now available on the
Get User Group operation
and can be used to include related users and dashboards in the response.
July 3rd 2024
A new operation Create Dashboard Backup is now available. This operation returns a JSON backup for a Cluvio dashboard that can later be used to create a new dashboard from a backup in the Cluvio App UI. See also Backup Dashboard in the Cluvio User Documentation.
Note: The backup JSON format is an internal format whose structure is not publicly documented and subject to change. Backup JSON files can only be used with the Cluvio App UI.
June 26th 2024
The all_time
aggregation option is now available and can be used as an input
value for a custom aggregation filter. Note that the filter must be explicitly
configured to allow "All Time" aggregation in order for the input value to be
accepted.
June 4th 2024
The sql_snippet
relationship has been added to SqlSnippet
response objects,
for example in the response of the Get SQL Snippet
operation.
Create Datasource
Create a new datasource for use with reports, filters, SQL alerts and SQL snippets.
The maximum number of datasources in your account is limited by your subscription plan.
See the Cluvio plan comparison.
The datasource Cluvio Sample Data
exists in every new subscription and does not count towards
your limit.
Authorizations:
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Responses
Response Schema: application/vnd.api+json
object (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "data": {
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "max_concurrent_executions": 20,
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
}
Response samples
- 201
- 403
- 422
{- "data": {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
}
List Datasources
Datasource credentials like the password
or bigquery_service_key
are only
included in the returned attributes if the API key has Manage Datasources
permission.
Authorizations:
query Parameters
include | string Value: "agents" [Optional] The relationship objects to include in the response. |
Responses
Response Schema: application/vnd.api+json
Array of objects (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (DatasourceAgent) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
|
Response samples
- 200
- 403
{- "data": [
- {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
], - "included": [
- {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}
]
}
Get Datasource
Datasource credentials like the password
or bigquery_service_key
are only
included in the returned attributes if the API key has Manage Datasources
permission.
Authorizations:
path Parameters
id | string |
query Parameters
include | string Value: "agents" [Optional] The relationship objects to include in the response. |
Responses
Response Schema: application/vnd.api+json
object (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (DatasourceAgent) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
|
Response samples
- 200
- 403
{- "data": {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}, - "included": [
- {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}
]
}
Update Datasource
Update a datasource to change connection parameters or configuration options.
Authorizations:
path Parameters
id | string |
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Responses
Response Schema: application/vnd.api+json
object (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "data": {
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "max_concurrent_executions": 20,
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
}
Response samples
- 200
- 403
- 422
{- "data": {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
}
Test Datasource Connection
Tests a datasource connection.
Authorizations:
path Parameters
id | string |
Responses
Response Schema: application/json
status | string Enum: "ok" "error" |
error_message | string The connection error message if the status is |
Response samples
- 200
- 403
{- "status": "ok",
- "error_message": "string"
}
Refresh Datasource
Refresh datasource metadata, including schema information.
On success this operation returns an execution ID that can be used to track the progress of the refresh operation.
Authorizations:
path Parameters
id | string |
Responses
Response Schema: application/json
execution_id | string <uuid> |
Response samples
- 200
- 403
{- "execution_id": "02ca5b65-a269-4c45-8d4a-0c74ff3ae670"
}
Get Datasource Schema
Get a data_key
and data_access_token
to get the datasource schema data
from a Cluvio data server.
Authorizations:
path Parameters
id | string |
query Parameters
name | string [Optional] The schema name. |
Responses
Response Schema: application/json
data_key | string |
data_access_token | string Use as authorization, together with the The response will be a single schema JSON when the schema query parameter was used, or full schema JSON otherwise. |
Response samples
- 200
- 403
{- "data_key": "string",
- "data_access_token": "string"
}
Create Datasource Agent
Create a new datasource agent.
A successful response contains a secret_key
attribute that must be safely
stored in the datasource agent configuration file. The datasource agent
uses the secret key to authenticate itself to the Cluvio servers when connecting.
After creating and connecting a new agent, it can be used by datasources with
connection mode agent
. See the updateDatasource
operation.
Authorizations:
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||
|
Responses
Response Schema: application/vnd.api+json
object (DatasourceAgentWithSecret) | |||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "data": {
- "attributes": {
- "name": "string",
- "enabled": true
}
}
}
Response samples
- 201
- 403
- 422
{- "data": {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "secret_key": "string"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}
}
List Datasource Agents
Authorizations:
query Parameters
include | string Value: "datasources" [Optional] The relationship objects to include in the response. |
Responses
Response Schema: application/vnd.api+json
Array of objects (DatasourceAgent) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
|
Response samples
- 200
- 403
{- "data": [
- {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}
], - "included": [
- {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
]
}
Get Datasource Agent
Get a datasource agent by ID.
Authorizations:
path Parameters
id | string |
query Parameters
include | string Value: "datasources" [Optional] The relationship objects to include in the response. |
Responses
Response Schema: application/vnd.api+json
object (DatasourceAgent) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of objects (Datasource) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
|
Response samples
- 200
- 403
{- "data": {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}, - "included": [
- {
- "id": "string",
- "type": "datasources",
- "attributes": {
- "name": "string",
- "database_type": "postgres",
- "connection_mode": "direct",
- "host": "string",
- "port": 0,
- "username": "string",
- "password": "string",
- "database": "string",
- "ssh_tunnel_host": "string",
- "ssh_tunnel_port": 0,
- "ssh_tunnel_user": "string",
- "data_time_zone": "Europe/Berlin",
- "require_ssl": true,
- "verify_ssl": false,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "schema_updated_at": "2019-08-24T14:15:22Z",
- "total_row_count": 0,
- "total_row_count_exact": true,
- "default_schema_name": "string",
- "max_concurrent_executions": 20,
- "server_version": "string",
- "update_schema_nightly": true,
- "update_schema_row_counts": true,
- "athena_region": "string",
- "athena_workgroup": "string",
- "databricks_http_path": "string",
- "snowflake_identifier": "string",
- "snowflake_region": "string",
- "snowflake_warehouse": "string",
- "bigquery_service_key": "string"
}, - "relationships": {
- "agents": {
- "data": [
- {
- "id": "lZ21oPaLUNWJbEifEhiFTaPIWlqaaZL3jxMA7L3h5Qg",
- "type": "datasource_agents"
}
]
}
}
}
]
}
Update Datasource Agent
A datasource agent can only be updated if the API key has Manage Datasources
permission
on all datasources that use the agent.
Authorizations:
path Parameters
id | string |
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||
|
Responses
Response Schema: application/vnd.api+json
object (DatasourceAgent) | |||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "data": {
- "attributes": {
- "name": "string",
- "enabled": true
}
}
}
Response samples
- 200
- 403
- 422
{- "data": {
- "id": "string",
- "type": "datasource_agents",
- "attributes": {
- "agent_id": "string",
- "name": "string",
- "version": "string",
- "address": "string",
- "connected": true,
- "active_queries": 0,
- "enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "datasources": {
- "data": [
- {
- "id": "8qxn-y9ex-65vd",
- "type": "datasources"
}
]
}
}
}
}
Run Execution
Run an ad hoc execution on a datasource.
An ad hoc execution consists of a SQL query, optionally an R query and input parameters for any Cluvio parameter expressions used in the SQL query. The R query can be used to post-process the SQL query results, see Using R in the user reference documentation for further details.
Poll the execution to check for progress, then get the execution data authorization to get the result data from a Cluvio data server.
Note: If the API key only has Manage Dashboards
or Manage Alerts
permission, it may be
restricted to a subset of datasources.
Authorizations:
Request Body schema: application/jsonrequired
sql_query required | string The SQL query to run. | ||||||||||||||
r_query | string The R query to run on the SQL results. | ||||||||||||||
object (InputParameters) | |||||||||||||||
|
Responses
Response Schema: application/vnd.api+json
object (Execution) | |||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "sql_query": "string",
- "r_query": "string",
- "parameters": {
- "timerange": "1712233090~1712237090",
- "aggregation": "second",
- "tz": "Europe/Berlin",
- "filters": [
- {
- "variable_name": "string",
- "selected_values": [
- 0
]
}
]
}
}
Response samples
- 200
- 403
- 422
{- "data": {
- "id": "string",
- "type": "executions",
- "attributes": {
- "execution_id": "02ca5b65-a269-4c45-8d4a-0c74ff3ae670",
- "execution_type": "sql_query",
- "execution_status": "starting",
- "result_columns": 0,
- "result_rows": 0,
- "result_size": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "started_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z"
}
}
}
Get Execution
Get the current state of an execution.
An execution is only available for 24 hours after it started.
Authorizations:
Responses
Response Schema: application/vnd.api+json
object (Execution) | |||||||||||||||||||||||||||||
|
Response samples
- 200
- 403
{- "data": {
- "id": "string",
- "type": "executions",
- "attributes": {
- "execution_id": "02ca5b65-a269-4c45-8d4a-0c74ff3ae670",
- "execution_type": "sql_query",
- "execution_status": "starting",
- "result_columns": 0,
- "result_rows": 0,
- "result_size": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "started_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z"
}
}
}
Get Execution Data
Get a data key and access token for an execution's result data.
Execution data is only available for 24 hours after an execution completed.
This operation results in a 204
response if the execution does not have data,
in which case it is either still running or did not complete successfully.
Authorizations:
Responses
Response Schema: application/json
data_key | string |
data_access_token | string Use as authorization, together with the The response will be JSON (content-type |
data_timestamp | integer <unix-time> |
Response samples
- 200
- 403
- 422
{- "data_key": "string",
- "data_access_token": "string",
- "data_timestamp": 0
}
Create Dashboard
Authorizations:
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Responses
Response Schema: application/vnd.api+json
object (Dashboard) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Request samples
- Payload
{- "data": {
- "attributes": {
- "name": "string",
- "description": "string",
- "time_zone_config": {
- "type": "disabled",
- "fixed_time_zone": "Europe/Berlin",
- "allowed_time_zones": [
- "Europe/Berlin"
]
}, - "automatic_update_enabled": true,
- "thumbnail_enabled": true,
- "prewarm": false,
- "data_refresh_rate": 1440,
- "data_refresh_anchor_time": "15:42",
- "is_locked": false,
- "default_parameters": {
- "timerange": "1712233090~1712237090",
- "aggregation": "second",
- "tz": "Europe/Berlin",
- "filters": [
- {
- "variable_name": "string",
- "selected_values": [
- 0
]
}
]
}, - "default_page_width": 1600,
- "layout": [
- {
- "type": "report",
- "id": "string",
- "row": 0,
- "column": 0,
- "width": 0,
- "height": 0
}
], - "color_scheme": "scheme_1",
- "filters_configuration": {
- "apply_immediately": true,
- "aggregation_options": [
- "second"
], - "filter_sorting": [
- "string"
], - "hidden_parameters": [
- "string"
]
}
}
}
}
Response samples
- 201
- 403
- 422
{- "data": {
- "id": "string",
- "type": "dashboards",
- "attributes": {
- "name": "string",
- "description": "string",
- "time_zone_config": {
- "type": "disabled",
- "fixed_time_zone": "Europe/Berlin",
- "allowed_time_zones": [
- "Europe/Berlin"
]
}, - "automatic_update_enabled": true,
- "thumbnail_enabled": true,
- "thumbnail_created_at": "2019-08-24T14:15:22Z",
- "prewarm": false,
- "published": true,
- "data_refresh_rate": 1440,
- "data_refresh_anchor_time": "15:42",
- "is_locked": false,
- "default_parameters": {
- "timerange": "1712233090~1712237090",
- "aggregation": "second",
- "tz": "Europe/Berlin",
- "filters": [
- {
- "variable_name": "string",
- "selected_values": [
- 0
]
}
]
}, - "default_page_width": 1600,
- "layout": [
- {
- "type": "report",
- "id": "string",
- "row": 0,
- "column": 0,
- "width": 0,
- "height": 0
}
], - "floating_enabled": false,
- "color_scheme": "scheme_1",
- "filters_configuration": {
- "apply_immediately": true,
- "aggregation_options": [
- "second"
], - "filter_sorting": [
- "string"
], - "hidden_parameters": [
- "string"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "reports": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "reports"
}
]
}, - "filters": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "filters"
}
]
}, - "sql_snippets": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "sql_snippets"
}
]
}, - "dashboard_groups": {
- "data": [
- {
- "id": "zxdr-j9y7-4g5p",
- "type": "dashboard_groups"
}
]
}, - "dashboard_sharing_links": {
- "data": [
- {
- "data": {
- "id": "8qxn-y9ex-65vd",
- "type": "dashboard_sharing_links"
}
}
]
}, - "user": {
- "data": {
- "id": "wej2-lzpx-84k3",
- "type": "users"
}
}, - "user_groups": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "user_groups"
}
]
}
}
}
}
List Dashboards
Authorizations:
Responses
Response Schema: application/vnd.api+json
Array of objects (Dashboard) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array
|
Response samples
- 200
- 403
- 422
{- "data": [
- {
- "id": "string",
- "type": "dashboards",
- "attributes": {
- "name": "string",
- "description": "string",
- "time_zone_config": {
- "type": "disabled",
- "fixed_time_zone": "Europe/Berlin",
- "allowed_time_zones": [
- "Europe/Berlin"
]
}, - "automatic_update_enabled": true,
- "thumbnail_enabled": true,
- "thumbnail_created_at": "2019-08-24T14:15:22Z",
- "prewarm": false,
- "published": true,
- "data_refresh_rate": 1440,
- "data_refresh_anchor_time": "15:42",
- "is_locked": false,
- "default_parameters": {
- "timerange": "1712233090~1712237090",
- "aggregation": "second",
- "tz": "Europe/Berlin",
- "filters": [
- {
- "variable_name": "string",
- "selected_values": [
- 0
]
}
]
}, - "default_page_width": 1600,
- "layout": [
- {
- "type": "report",
- "id": "string",
- "row": 0,
- "column": 0,
- "width": 0,
- "height": 0
}
], - "floating_enabled": false,
- "color_scheme": "scheme_1",
- "filters_configuration": {
- "apply_immediately": true,
- "aggregation_options": [
- "second"
], - "filter_sorting": [
- "string"
], - "hidden_parameters": [
- "string"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "reports": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "reports"
}
]
}, - "filters": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "filters"
}
]
}, - "sql_snippets": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "sql_snippets"
}
]
}, - "dashboard_groups": {
- "data": [
- {
- "id": "zxdr-j9y7-4g5p",
- "type": "dashboard_groups"
}
]
}, - "dashboard_sharing_links": {
- "data": [
- {
- "data": {
- "id": "8qxn-y9ex-65vd",
- "type": "dashboard_sharing_links"
}
}
]
}, - "user": {
- "data": {
- "id": "wej2-lzpx-84k3",
- "type": "users"
}
}, - "user_groups": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "user_groups"
}
]
}
}
}
]
}
Get Dashboard
Authorizations:
path Parameters
id | string |
query Parameters
include | string Enum: "reports" "filters" "sql_snippets" "dashboard_groups" "dashboard_sharing_links" "user" "user_groups" [Optional] The relationship objects to include in the Including Including |
Responses
Response Schema: application/vnd.api+json
object (Dashboard) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array of User (object) or Report (object) or UserGroup (object) or DashboardGroup (object) or Filter (object) or SqlSnippet (object) or DashboardSharingLink (object) The optionally included relationship objects. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Array One of
|
Response samples
- 200
- 403
{- "data": {
- "id": "string",
- "type": "dashboards",
- "attributes": {
- "name": "string",
- "description": "string",
- "time_zone_config": {
- "type": "disabled",
- "fixed_time_zone": "Europe/Berlin",
- "allowed_time_zones": [
- "Europe/Berlin"
]
}, - "automatic_update_enabled": true,
- "thumbnail_enabled": true,
- "thumbnail_created_at": "2019-08-24T14:15:22Z",
- "prewarm": false,
- "published": true,
- "data_refresh_rate": 1440,
- "data_refresh_anchor_time": "15:42",
- "is_locked": false,
- "default_parameters": {
- "timerange": "1712233090~1712237090",
- "aggregation": "second",
- "tz": "Europe/Berlin",
- "filters": [
- {
- "variable_name": "string",
- "selected_values": [
- 0
]
}
]
}, - "default_page_width": 1600,
- "layout": [
- {
- "type": "report",
- "id": "string",
- "row": 0,
- "column": 0,
- "width": 0,
- "height": 0
}
], - "floating_enabled": false,
- "color_scheme": "scheme_1",
- "filters_configuration": {
- "apply_immediately": true,
- "aggregation_options": [
- "second"
], - "filter_sorting": [
- "string"
], - "hidden_parameters": [
- "string"
]
}, - "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "reports": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "reports"
}
]
}, - "filters": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "filters"
}
]
}, - "sql_snippets": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "sql_snippets"
}
]
}, - "dashboard_groups": {
- "data": [
- {
- "id": "zxdr-j9y7-4g5p",
- "type": "dashboard_groups"
}
]
}, - "dashboard_sharing_links": {
- "data": [
- {
- "data": {
- "id": "8qxn-y9ex-65vd",
- "type": "dashboard_sharing_links"
}
}
]
}, - "user": {
- "data": {
- "id": "wej2-lzpx-84k3",
- "type": "users"
}
}, - "user_groups": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "user_groups"
}
]
}
}
}, - "included": [
- {
- "id": "zg6p-xee0-x9jy",
- "type": "users",
- "attributes": {
- "firstname": "string",
- "lastname": "string",
- "email": "user@example.com",
- "role": "viewer",
- "otp_app_enabled": true,
- "otp_phone_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "deactivated_at": "2019-08-24T14:15:22Z",
- "invitation_created_at": "2019-08-24T14:15:22Z",
- "invitation_accepted_at": "2019-08-24T14:15:22Z"
}, - "relationships": {
- "user_groups": {
- "data": [
- {
- "id": "qw1x-7w2l-7rd5",
- "type": "user_groups"
}
]
}, - "invited_by_user": {
- "data": {
- "id": "wej2-lzpx-84k3",
- "type": "users"
}
}
}
}
]
}
Update Dashboard
Authorizations:
path Parameters
id | string |
Request Body schema: application/vnd.api+jsonrequired
object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Responses
Response Schema: application/vnd.api+json
object (Dashboard) | |||||||||||||
|