Skip to main content

Cluvio API (v2024-06-01)

Introduction

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.

Servers

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

US Servers

API Keys

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.

Data Access Tokens

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.

Changelog

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.

Datasources

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:
ApiKey
Request Body schema: application/vnd.api+json
required
object
object (DatasourceAttributes)
name
required
string
database_type
required
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
required
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
max_concurrent_executions
integer
Default: 20
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Responses

Response Schema: application/vnd.api+json
object (Datasource)
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Request samples

Content type
application/vnd.api+json
{
  • "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

Content type
application/vnd.api+json
{
  • "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:
ApiKeyApiKeyApiKeyApiKey
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
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"
Array of objects (DatasourceAgent)
Array
id
string
type
string
Value: "datasource_agents"
object (DatasourceAgentAttributes)
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKeyApiKeyApiKeyApiKey
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)
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"
Array of objects (DatasourceAgent)
Array
id
string
type
string
Value: "datasource_agents"
object (DatasourceAgentAttributes)
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKey
path Parameters
id
string
Request Body schema: application/vnd.api+json
required
object
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
max_concurrent_executions
integer
Default: 20
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Responses

Response Schema: application/vnd.api+json
object (Datasource)
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Request samples

Content type
application/vnd.api+json
{
  • "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

Content type
application/vnd.api+json
{
  • "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"
            }
          ]
        }
      }
    }
}

Delete Datasource

A datasource can only be deleted if it is not used by any report or filter.

Authorizations:
ApiKey
path Parameters
id
string

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "code": "422",
      • "detail": "A detailed description of the error."
      }
    ]
}

Test Datasource Connection

Tests a datasource connection.

Authorizations:
ApiKey
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 error.

Response samples

Content type
application/json
{
  • "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:
ApiKey
path Parameters
id
string

Responses

Response Schema: application/json
execution_id
string <uuid>

Response samples

Content type
application/json
{
  • "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:
ApiKeyApiKeyApiKeyApiKey
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 data_key, to fetch the schema using the Get Schema Data operation on a Cluvio Data Server.

The response will be a single schema JSON when the schema query parameter was used, or full schema JSON otherwise.

Response samples

Content type
application/json
{
  • "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:
ApiKey
Request Body schema: application/vnd.api+json
required
object
object (DatasourceAgentAttributes)
name
required
string
enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

Responses

Response Schema: application/vnd.api+json
object (DatasourceAgentWithSecret)
id
string
type
string
Value: "datasource_agents"
object
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
secret_key
string

The generated secret key for the new agent.

The secret key is only returned once when creating a new agent. The secret key must be included in the datasource agent configuration and is used by the agent to authenticate itself to the Cluvio servers when connecting.

object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "string",
      • "enabled": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKeyApiKey
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
id
string
type
string
Value: "datasource_agents"
object (DatasourceAgentAttributes)
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"
Array of objects (Datasource)
Array
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKeyApiKey
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)
id
string
type
string
Value: "datasource_agents"
object (DatasourceAgentAttributes)
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"
Array of objects (Datasource)
Array
id
string
type
string
Value: "datasources"
object (DatasourceAttributes)
name
string
database_type
string
Enum: "postgres" "redshift" "mysql" "mariadb" "oracle" "mssql" "bigquery" "athena" "presto" "trino" "snowflake" "vertica" "mongodb" "databricks"
connection_mode
string
Enum: "direct" "ssh_tunnel" "agent"
host
string

The database hostname to connect to.

Not applicable to BigQuery or Athena datasources.

port
integer

The database port to connect to.

Not applicable to BigQuery, Athena and Snowflake datasources.

username
string

The database username to use when connecting.

For BigQuery datasources, this must be the Project ID.

password
string

The database password to use when connecting.

Not applicable to BigQuery datasources. See bigquery_service_key for configuring BigQuery Service Account credentials.

database
string

The name of the database to connect to.

For BigQuery datasources, the value is optional and specifies the dataset to use. If set, the BigQuery datasource is restricted to this dataset.

ssh_tunnel_host
string

Only for connection_mode ssh_tunnel

ssh_tunnel_port
integer

Only for connection_mode ssh_tunnel

ssh_tunnel_user
string

Only for connection_mode ssh_tunnel

data_time_zone
string

The data time zone to use for the datasource.

require_ssl
boolean

Always true for database_type athena, bigquery, databricks, redshift or snowflake. Defaults to true for connection_mode direct.

verify_ssl
boolean
Default: false

Only for connection_mode direct. Always true for database_type athena, bigquery, databricks or snowflake. Always true for database_type oracle or presto when require_ssl is true.

enabled
boolean
Default: true
created_at
string <date-time>
updated_at
string <date-time>
schema_updated_at
string <date-time>
total_row_count
integer
total_row_count_exact
boolean
default_schema_name
string
max_concurrent_executions
integer
Default: 20
server_version
string
update_schema_nightly
boolean
Default: true
update_schema_row_counts
boolean
Default: true
athena_region
string

The Athena region to connect to.

Only for database type athena.

athena_workgroup
string

The Athena workgroup to connect to.

databricks_http_path
string

The Databricks HTTP path to connect to.

snowflake_identifier
string

The Snowflake account identifier to use.

snowflake_region
string

The Snowflake region to connect to.

snowflake_warehouse
string

The Snowflake warehouse to connect to.

bigquery_service_key
string

The BigQuery Service Key as a JSON string.

object (DatasourceRelationships)
object

The datasource agents used by the datasource to connect to the upstream database.

Only applicable to datasources with connection mode agent.

Array of objects (DatasourceAgentRef)
Array
id
string
type
string
Value: "datasource_agents"

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKey
path Parameters
id
string
Request Body schema: application/vnd.api+json
required
object
object (DatasourceAgentAttributes)
name
string
enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

Responses

Response Schema: application/vnd.api+json
object (DatasourceAgent)
id
string
type
string
Value: "datasource_agents"
object (DatasourceAgentAttributes)
agent_id
string
name
string
version
string

The last known version of the agent.

If the agent is connected, this is the version of the connected agent. If the agent is not connected, this is the version of the agent when it was last connected.

address
string <ip>

The last known IP address of the agent.

If the agent is connected, this is the IP address of the agent as seen by the Cluvio servers. If the agent is disconnected, this is the IP address of the agent when it was last connected.

connected
boolean

Whether the agent is connected.

active_queries
integer

The approximate current number of running queries on the agent.

enabled
boolean
Default: true

Whether the agent is enabled.

Only enabled agents can connect to Cluvio servers. When a connected agent is disabled, it is disconnected.

created_at
string <date-time>
updated_at
string <date-time>
object (DatasourceAgentRelationships)
object

The datasources that use the agent.

Array of objects (DatasourceRef)
Array
id
string
type
string
Value: "datasources"

Request samples

Content type
application/vnd.api+json
{
  • "data": {
    • "attributes": {
      • "name": "string",
      • "enabled": true
      }
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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"
            }
          ]
        }
      }
    }
}

Delete Datasource Agent

A datasource agent can only be deleted if it is not used by any datasource.

Authorizations:
ApiKey
path Parameters
id
string

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "code": "422",
      • "detail": "A detailed description of the error."
      }
    ]
}

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:
ApiKeyApiKeyApiKey
Request Body schema: application/json
required
sql_query
required
string

The SQL query to run.

r_query
string

The R query to run on the SQL results.

object (InputParameters)
timerange
string

The input value for the built-in timerange filter, in the format <unix-start-time>~<unix-end-time>. Both range boundaries are optional and inclusive, e.g. ~ specifies an unbounded timerange.

aggregation
string (AggregationOption)
Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"

The input value for the built-in aggregation filter.

tz
string

The input value for the dashboard time zone, if the dashboard is configured to accept an input time zone.

Array of objects (FilterInput)

Input values for custom filters.

Array
variable_name
string
selected_values
Array of numbers or strings or booleans or null

Responses

Response Schema: application/vnd.api+json
object (Execution)
id
string
type
string
Value: "executions"
object (ExecutionAttributes)
execution_id
string <uuid>
execution_type
string
Enum: "sql_query" "sql_filter" "sql_alert" "almanach_query" "export_query"
execution_status
string
Enum: "starting" "running" "waiting" "scheduled" "cancelled" "success" "query_error" "timed_out" "internal_error" "internal_timeout"
result_columns
integer
result_rows
integer
result_size
integer
created_at
string <date-time>
updated_at
string <date-time>
started_at
string <date-time>
completed_at
string <date-time>

Request samples

Content type
application/json
{
  • "sql_query": "string",
  • "r_query": "string",
  • "parameters": {
    • "timerange": "1712233090~1712237090",
    • "aggregation": "second",
    • "tz": "Europe/Berlin",
    • "filters": [
      • {
        • "variable_name": "string",
        • "selected_values": [
          • 0
          ]
        }
      ]
    }
}

Response samples

Content type
application/vnd.api+json
{
  • "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:
ApiKeyApiKeyApiKeyApiKeyApiKey

Responses

Response Schema: application/vnd.api+json
object (Execution)
id
string
type
string
Value: "executions"
object (ExecutionAttributes)
execution_id
string <uuid>
execution_type
string
Enum: "sql_query" "sql_filter" "sql_alert" "almanach_query" "export_query"
execution_status
string
Enum: "starting" "running" "waiting" "scheduled" "cancelled" "success" "query_error" "timed_out" "internal_error" "internal_timeout"
result_columns
integer
result_rows
integer
result_size
integer
created_at
string <date-time>
updated_at
string <date-time>
started_at
string <date-time>
completed_at
string <date-time>

Response samples

Content type
application/vnd.api+json
{
  • "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"
      }
    }
}

Cancel Execution

Cancel a running execution.

If the execution already completed, this operation has no effect.

Authorizations:
ApiKeyApiKeyApiKey

Responses

Response samples

Content type
application/vnd.api+json
{
  • "errors": [
    • {
      • "code": "422",
      • "detail": "A detailed description of the error."
      }
    ]
}

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:
ApiKeyApiKeyApiKeyApiKeyApiKey

Responses

Response Schema: application/json
data_key
string
data_access_token
string

Use as authorization, together with the data_key to fetch the result data using the Get Result Data operation on a Cluvio Data Server.

The response will be JSON (content-type application/json).

data_timestamp
integer <unix-time>

Response samples

Content type
application/json
{
  • "data_key": "string",
  • "data_access_token": "string",
  • "data_timestamp": 0
}

Dashboards

Create Dashboard

Authorizations:
ApiKey
Request Body schema: application/vnd.api+json
required
object
object (DashboardAttributes)
name
required
string
description
string
object (TimeZoneConfig)
Default: {"type":"disabled"}
type
string
Default: "disabled"
Enum: "disabled" "organization" "fixed" "input"
fixed_time_zone
string

Only for type fixed

allowed_time_zones
Array of strings

Only for type input

automatic_update_enabled
boolean
Default: true

Whether automatic dashboard updates are enabled.

Automatic dashboard updates are enabled by default and result in the Cluvio App periodically checking the status of the dashboard when it is viewed in a web browser.

thumbnail_enabled
boolean
Default: true

Whether automatic thumbnail generation is enabled.

Thumbnail generation is enabled by default. Note that thumbnails are only updated at most once a day and only for dashboards that have been accessed in the last 24 hours.

prewarm
boolean
Default: false
data_refresh_rate
number
Default: 1440

The data refresh rate of the dashboard, in minutes.

The data refresh rate specifies the maximum age of cached query results for reports and filters. The dashboard's refresh rate applies to all reports and SQL filters on the dashboard, unless a report or filter has a lower refresh rate configured.

The default is 24 hours.

data_refresh_anchor_time
string <time>

The data refresh anchor time defines a maximum age of cached query results for reports and filters such that results are considered out-of-date when they predate the anchor time on the current day (in the organization's time zone).

For example, an anchor time can be used to ensure that a dashboard never shows data from yesterday by setting the anchor time to midnight 00:00, or that the dashboard always shows the latest data after a nightly database synchronization, e.g. by setting the anchor time to a time-of-day after the nightly synchronization.

is_locked
boolean
Default: false
object (InputParameters)

Default input parameters for the dashboard's filters.

Note: Can only be set on existing dashboards.

timerange
string

The input value for the built-in timerange filter, in the format <unix-start-time>~<unix-end-time>. Both range boundaries are optional and inclusive, e.g. ~ specifies an unbounded timerange.

aggregation
string (AggregationOption)
Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"

The input value for the built-in aggregation filter.

tz
string

The input value for the dashboard time zone, if the dashboard is configured to accept an input time zone.

Array of objects (FilterInput)

Input values for custom filters.

default_page_width
integer
Default: 1600

The default width in pixels of rendered PDFs and PNGs for this dashboard.

color_scheme
string
Default: "scheme_6"
Enum: "scheme_1" "scheme_2" "scheme_3" "scheme_4" "scheme_5" "scheme_6" "scheme_7" "scheme_8"

The dashboard's color scheme. The following built-in color schemes exist:

  • scheme_1: Blue Ocean
  • scheme_2: Bluegrass
  • scheme_3: Green Meadow
  • scheme_4: Violet Sky
  • scheme_5: Vibrant Sunset
  • scheme_6: Colorful
  • scheme_7: Colorful Variant 2
  • scheme_8: Colorful Variant 3
object (DashboardFiltersConfig)
Default: {}
apply_immediately
boolean

Whether each individual filter value selection in the Cluvio filter bar should be applied to reports and other filters on the dashboard immediately.

Note: Multi-select filters always require confirmation of the selection.

aggregation_options
Array of strings (AggregationOption)
Items Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"
filter_sorting
Array of strings

List of filter variable names used on the dashboard determining their order of appearance (left-to-right, top-to-bottom).

Any dashboard filters not included in the list are sorted at the end.

hidden_parameters
Array of strings

Responses

Response Schema: application/vnd.api+json
object (Dashboard)
id
string
type
string
Value: "dashboards"
object (DashboardAttributes)
name
string
description
string
object (TimeZoneConfig)
Default: {"type":"disabled"}
type
string
Default: "disabled"
Enum: "disabled" "organization" "fixed" "input"
fixed_time_zone
string

Only for type fixed

allowed_time_zones
Array of strings

Only for type input

automatic_update_enabled
boolean
Default: true

Whether automatic dashboard updates are enabled.

Automatic dashboard updates are enabled by default and result in the Cluvio App periodically checking the status of the dashboard when it is viewed in a web browser.

thumbnail_enabled
boolean
Default: true

Whether automatic thumbnail generation is enabled.

Thumbnail generation is enabled by default. Note that thumbnails are only updated at most once a day and only for dashboards that have been accessed in the last 24 hours.

thumbnail_image_url
string <uri>
thumbnail_created_at
string <date-time>
prewarm
boolean
Default: false
published
boolean

Whether the dashboard is shared with any user groups.

data_refresh_rate
number
Default: 1440

The data refresh rate of the dashboard, in minutes.

The data refresh rate specifies the maximum age of cached query results for reports and filters. The dashboard's refresh rate applies to all reports and SQL filters on the dashboard, unless a report or filter has a lower refresh rate configured.

The default is 24 hours.

data_refresh_anchor_time
string <time>

The data refresh anchor time defines a maximum age of cached query results for reports and filters such that results are considered out-of-date when they predate the anchor time on the current day (in the organization's time zone).

For example, an anchor time can be used to ensure that a dashboard never shows data from yesterday by setting the anchor time to midnight 00:00, or that the dashboard always shows the latest data after a nightly database synchronization, e.g. by setting the anchor time to a time-of-day after the nightly synchronization.

is_locked
boolean
Default: false
object (InputParameters)

Default input parameters for the dashboard's filters.

Note: Can only be set on existing dashboards.

timerange
string

The input value for the built-in timerange filter, in the format <unix-start-time>~<unix-end-time>. Both range boundaries are optional and inclusive, e.g. ~ specifies an unbounded timerange.

aggregation
string (AggregationOption)
Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"

The input value for the built-in aggregation filter.

tz
string

The input value for the dashboard time zone, if the dashboard is configured to accept an input time zone.

Array of objects (FilterInput)

Input values for custom filters.

default_page_width
integer
Default: 1600

The default width in pixels of rendered PDFs and PNGs for this dashboard.

Array of objects (DashboardLayout)

The layout of the dashboard content elements.

To update the layout, use the Update Dashboard Layout operation.

Array
type
string
Value: "report"
id
string

The ID of the dashboard content element.

row
integer

The vertical position (Y-coordinate) of the content element on the dashboard's layout grid.

The minimum value is 1.

column
integer

The horizontal position (X-coordinate) of the content element on the dashboard's layout grid.

The minimum value is 1 and the maximum value is 12.

width
integer

The width of the content element on the dashboard's layout grid.

The minimum value is 1 and the maximum value is 12.

height
integer

The height of the content element on the dashboard's layout grid.

The minimum value is 1.

floating_enabled
boolean
Default: false

Whether "floating" content is allow on the dashboard. Floating content is any dashboard content whose top border is not anchored to another dashboard content element or the Cluvio toolbar.

To update this setting, use the Update Dashboard Layout operation.

color_scheme
string
Default: "scheme_6"
Enum: "scheme_1" "scheme_2" "scheme_3" "scheme_4" "scheme_5" "scheme_6" "scheme_7" "scheme_8"

The dashboard's color scheme. The following built-in color schemes exist:

  • scheme_1: Blue Ocean
  • scheme_2: Bluegrass
  • scheme_3: Green Meadow
  • scheme_4: Violet Sky
  • scheme_5: Vibrant Sunset
  • scheme_6: Colorful
  • scheme_7: Colorful Variant 2
  • scheme_8: Colorful Variant 3
object (DashboardFiltersConfig)
Default: {}
apply_immediately
boolean

Whether each individual filter value selection in the Cluvio filter bar should be applied to reports and other filters on the dashboard immediately.

Note: Multi-select filters always require confirmation of the selection.

aggregation_options
Array of strings (AggregationOption)
Items Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"
filter_sorting
Array of strings

List of filter variable names used on the dashboard determining their order of appearance (left-to-right, top-to-bottom).

Any dashboard filters not included in the list are sorted at the end.

hidden_parameters
Array of strings
created_at
string <date-time>
updated_at
string <date-time>
object (DashboardRelationships)
object
Array of objects (ReportRef)
Array
id
string
type
string
Value: "reports"
object
Array of objects (FilterRef)
Array
id
string
type
string
Value: "filters"
object
Array of objects (SqlSnippetRef)
Array
id
string
type
string
Value: "sql_snippets"
object
Array of objects (DashboardGroupRef)
Array
id
string
type
string
Value: "dashboard_groups"
object
Array of objects (DashboardSharingLinkRef)

The sharing links of the dashboard.

Only present if the API key has Manage Dashboards permission.

Array
object
id
string
type
string
Value: "dashboard_sharing_links"
object
object (UserRef)

The owner of the dashboard.

Only present if the API key has View Users, Manage Users or Manage Dashboards permission.

id
string
type
string
Value: "users"
object
Array of objects (UserGroupRef)

The user groups the dashboard is shared with.

Only present if the API key has View Users, Manage Users or Manage Dashboards permission.

Array
id
string
type
string
Value: "user_groups"

Request samples

Content type
application/vnd.api+json
{
  • "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

Content type
application/vnd.api+json
{
  • "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_image_url": "http://example.com",
      • "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:
ApiKeyApiKeyApiKey

Responses

Response Schema: application/vnd.api+json
Array of objects (Dashboard)
Array
id
string
type
string
Value: "dashboards"
object (DashboardAttributes)
name
string
description
string
object (TimeZoneConfig)
Default: {"type":"disabled"}
automatic_update_enabled
boolean
Default: true

Whether automatic dashboard updates are enabled.

Automatic dashboard updates are enabled by default and result in the Cluvio App periodically checking the status of the dashboard when it is viewed in a web browser.

thumbnail_enabled
boolean
Default: true

Whether automatic thumbnail generation is enabled.

Thumbnail generation is enabled by default. Note that thumbnails are only updated at most once a day and only for dashboards that have been accessed in the last 24 hours.

thumbnail_image_url
string <uri>
thumbnail_created_at
string <date-time>
prewarm
boolean
Default: false
published
boolean

Whether the dashboard is shared with any user groups.

data_refresh_rate
number
Default: 1440

The data refresh rate of the dashboard, in minutes.

The data refresh rate specifies the maximum age of cached query results for reports and filters. The dashboard's refresh rate applies to all reports and SQL filters on the dashboard, unless a report or filter has a lower refresh rate configured.

The default is 24 hours.

data_refresh_anchor_time
string <time>

The data refresh anchor time defines a maximum age of cached query results for reports and filters such that results are considered out-of-date when they predate the anchor time on the current day (in the organization's time zone).

For example, an anchor time can be used to ensure that a dashboard never shows data from yesterday by setting the anchor time to midnight 00:00, or that the dashboard always shows the latest data after a nightly database synchronization, e.g. by setting the anchor time to a time-of-day after the nightly synchronization.

is_locked
boolean
Default: false
object (InputParameters)

Default input parameters for the dashboard's filters.

Note: Can only be set on existing dashboards.

default_page_width
integer
Default: 1600

The default width in pixels of rendered PDFs and PNGs for this dashboard.

Array of objects (DashboardLayout)

The layout of the dashboard content elements.

To update the layout, use the Update Dashboard Layout operation.

floating_enabled
boolean
Default: false

Whether "floating" content is allow on the dashboard. Floating content is any dashboard content whose top border is not anchored to another dashboard content element or the Cluvio toolbar.

To update this setting, use the Update Dashboard Layout operation.

color_scheme
string
Default: "scheme_6"
Enum: "scheme_1" "scheme_2" "scheme_3" "scheme_4" "scheme_5" "scheme_6" "scheme_7" "scheme_8"

The dashboard's color scheme. The following built-in color schemes exist:

  • scheme_1: Blue Ocean
  • scheme_2: Bluegrass
  • scheme_3: Green Meadow
  • scheme_4: Violet Sky
  • scheme_5: Vibrant Sunset
  • scheme_6: Colorful
  • scheme_7: Colorful Variant 2
  • scheme_8: Colorful Variant 3
object (DashboardFiltersConfig)
Default: {}
created_at
string <date-time>
updated_at
string <date-time>
object (DashboardRelationships)
object
object
object
object
object
object
object

Response samples

Content type
application/vnd.api+json
{
  • "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_image_url": "http://example.com",
        • "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:
ApiKeyApiKeyApiKey
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 included section of the response.

Including user or user_groups requires View Users, Manage Users or Manage Dashboards permission.

Including dashboard_sharing_links requires Manage Dashboards permission.

Responses

Response Schema: application/vnd.api+json
object (Dashboard)
id
string
type
string
Value: "dashboards"
object (DashboardAttributes)
name
string
description
string
object (TimeZoneConfig)
Default: {"type":"disabled"}
type
string
Default: "disabled"
Enum: "disabled" "organization" "fixed" "input"
fixed_time_zone
string

Only for type fixed

allowed_time_zones
Array of strings

Only for type input

automatic_update_enabled
boolean
Default: true

Whether automatic dashboard updates are enabled.

Automatic dashboard updates are enabled by default and result in the Cluvio App periodically checking the status of the dashboard when it is viewed in a web browser.

thumbnail_enabled
boolean
Default: true

Whether automatic thumbnail generation is enabled.

Thumbnail generation is enabled by default. Note that thumbnails are only updated at most once a day and only for dashboards that have been accessed in the last 24 hours.

thumbnail_image_url
string <uri>
thumbnail_created_at
string <date-time>
prewarm
boolean
Default: false
published
boolean

Whether the dashboard is shared with any user groups.

data_refresh_rate
number
Default: 1440

The data refresh rate of the dashboard, in minutes.

The data refresh rate specifies the maximum age of cached query results for reports and filters. The dashboard's refresh rate applies to all reports and SQL filters on the dashboard, unless a report or filter has a lower refresh rate configured.

The default is 24 hours.

data_refresh_anchor_time
string <time>

The data refresh anchor time defines a maximum age of cached query results for reports and filters such that results are considered out-of-date when they predate the anchor time on the current day (in the organization's time zone).

For example, an anchor time can be used to ensure that a dashboard never shows data from yesterday by setting the anchor time to midnight 00:00, or that the dashboard always shows the latest data after a nightly database synchronization, e.g. by setting the anchor time to a time-of-day after the nightly synchronization.

is_locked
boolean
Default: false
object (InputParameters)

Default input parameters for the dashboard's filters.

Note: Can only be set on existing dashboards.

timerange
string

The input value for the built-in timerange filter, in the format <unix-start-time>~<unix-end-time>. Both range boundaries are optional and inclusive, e.g. ~ specifies an unbounded timerange.

aggregation
string (AggregationOption)
Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"

The input value for the built-in aggregation filter.

tz
string

The input value for the dashboard time zone, if the dashboard is configured to accept an input time zone.

Array of objects (FilterInput)

Input values for custom filters.

default_page_width
integer
Default: 1600

The default width in pixels of rendered PDFs and PNGs for this dashboard.

Array of objects (DashboardLayout)

The layout of the dashboard content elements.

To update the layout, use the Update Dashboard Layout operation.

Array
type
string
Value: "report"
id
string

The ID of the dashboard content element.

row
integer

The vertical position (Y-coordinate) of the content element on the dashboard's layout grid.

The minimum value is 1.

column
integer

The horizontal position (X-coordinate) of the content element on the dashboard's layout grid.

The minimum value is 1 and the maximum value is 12.

width
integer

The width of the content element on the dashboard's layout grid.

The minimum value is 1 and the maximum value is 12.

height
integer

The height of the content element on the dashboard's layout grid.

The minimum value is 1.

floating_enabled
boolean
Default: false

Whether "floating" content is allow on the dashboard. Floating content is any dashboard content whose top border is not anchored to another dashboard content element or the Cluvio toolbar.

To update this setting, use the Update Dashboard Layout operation.

color_scheme
string
Default: "scheme_6"
Enum: "scheme_1" "scheme_2" "scheme_3" "scheme_4" "scheme_5" "scheme_6" "scheme_7" "scheme_8"

The dashboard's color scheme. The following built-in color schemes exist:

  • scheme_1: Blue Ocean
  • scheme_2: Bluegrass
  • scheme_3: Green Meadow
  • scheme_4: Violet Sky
  • scheme_5: Vibrant Sunset
  • scheme_6: Colorful
  • scheme_7: Colorful Variant 2
  • scheme_8: Colorful Variant 3
object (DashboardFiltersConfig)
Default: {}
apply_immediately
boolean

Whether each individual filter value selection in the Cluvio filter bar should be applied to reports and other filters on the dashboard immediately.

Note: Multi-select filters always require confirmation of the selection.

aggregation_options
Array of strings (AggregationOption)
Items Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"
filter_sorting
Array of strings

List of filter variable names used on the dashboard determining their order of appearance (left-to-right, top-to-bottom).

Any dashboard filters not included in the list are sorted at the end.

hidden_parameters
Array of strings
created_at
string <date-time>
updated_at
string <date-time>
object (DashboardRelationships)
object
Array of objects (ReportRef)
Array
id
string
type
string
Value: "reports"
object
Array of objects (FilterRef)
Array
id
string
type
string
Value: "filters"
object
Array of objects (SqlSnippetRef)
Array
id
string
type
string
Value: "sql_snippets"
object
Array of objects (DashboardGroupRef)
Array
id
string
type
string
Value: "dashboard_groups"
object
Array of objects (DashboardSharingLinkRef)

The sharing links of the dashboard.

Only present if the API key has Manage Dashboards permission.

Array
object
id
string
type
string
Value: "dashboard_sharing_links"
object
object (UserRef)

The owner of the dashboard.

Only present if the API key has View Users, Manage Users or Manage Dashboards permission.

id
string
type
string
Value: "users"
object
Array of objects (UserGroupRef)

The user groups the dashboard is shared with.

Only present if the API key has View Users, Manage Users or Manage Dashboards permission.

Array
id
string
type
string
Value: "user_groups"
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
id
string
type
string
Value: "users"
object (UserAttributes)
firstname
string
lastname
string
email
string <email>
role
string
Enum: "viewer" "analyst" "admin"
otp_app_enabled
boolean

Only present if the API key has Manage Users permission.

otp_phone_enabled
boolean

Only present if the API key has Manage Users permission.

created_at
string <date-time>

The date & time when the user was created.

deactivated_at
string <date-time>

The date & time when the user was deactivated.

invitation_created_at
string <date-time>

The date & time when the user invitation was sent.

invitation_accepted_at
string <date-time>

The date & time when the user invitation was accepted.

object (UserRelationships)
object
object

Response samples

Content type
application/vnd.api+json
{
  • "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_image_url": "http://example.com",
      • "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:
ApiKey
path Parameters
id
string
Request Body schema: application/vnd.api+json
required
object
object (DashboardAttributes)
name
string
description
string
object (TimeZoneConfig)
Default: {"type":"disabled"}
type
string
Default: "disabled"
Enum: "disabled" "organization" "fixed" "input"
fixed_time_zone
string

Only for type fixed

allowed_time_zones
Array of strings

Only for type input

automatic_update_enabled
boolean
Default: true

Whether automatic dashboard updates are enabled.

Automatic dashboard updates are enabled by default and result in the Cluvio App periodically checking the status of the dashboard when it is viewed in a web browser.

thumbnail_enabled
boolean
Default: true

Whether automatic thumbnail generation is enabled.

Thumbnail generation is enabled by default. Note that thumbnails are only updated at most once a day and only for dashboards that have been accessed in the last 24 hours.

prewarm
boolean
Default: false
data_refresh_rate
number
Default: 1440

The data refresh rate of the dashboard, in minutes.

The data refresh rate specifies the maximum age of cached query results for reports and filters. The dashboard's refresh rate applies to all reports and SQL filters on the dashboard, unless a report or filter has a lower refresh rate configured.

The default is 24 hours.

data_refresh_anchor_time
string <time>

The data refresh anchor time defines a maximum age of cached query results for reports and filters such that results are considered out-of-date when they predate the anchor time on the current day (in the organization's time zone).

For example, an anchor time can be used to ensure that a dashboard never shows data from yesterday by setting the anchor time to midnight 00:00, or that the dashboard always shows the latest data after a nightly database synchronization, e.g. by setting the anchor time to a time-of-day after the nightly synchronization.

is_locked
boolean
Default: false
object (InputParameters)

Default input parameters for the dashboard's filters.

Note: Can only be set on existing dashboards.

timerange
string

The input value for the built-in timerange filter, in the format <unix-start-time>~<unix-end-time>. Both range boundaries are optional and inclusive, e.g. ~ specifies an unbounded timerange.

aggregation
string (AggregationOption)
Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"

The input value for the built-in aggregation filter.

tz
string

The input value for the dashboard time zone, if the dashboard is configured to accept an input time zone.

Array of objects (FilterInput)

Input values for custom filters.

default_page_width
integer
Default: 1600

The default width in pixels of rendered PDFs and PNGs for this dashboard.

color_scheme
string
Default: "scheme_6"
Enum: "scheme_1" "scheme_2" "scheme_3" "scheme_4" "scheme_5" "scheme_6" "scheme_7" "scheme_8"

The dashboard's color scheme. The following built-in color schemes exist:

  • scheme_1: Blue Ocean
  • scheme_2: Bluegrass
  • scheme_3: Green Meadow
  • scheme_4: Violet Sky
  • scheme_5: Vibrant Sunset
  • scheme_6: Colorful
  • scheme_7: Colorful Variant 2
  • scheme_8: Colorful Variant 3
object (DashboardFiltersConfig)
Default: {}
apply_immediately
boolean

Whether each individual filter value selection in the Cluvio filter bar should be applied to reports and other filters on the dashboard immediately.

Note: Multi-select filters always require confirmation of the selection.

aggregation_options
Array of strings (AggregationOption)
Items Enum: "second" "minute" "hour" "day" "week" "week_sunday" "month" "quarter" "year" "all_time"
filter_sorting
Array of strings

List of filter variable names used on the dashboard determining their order of appearance (left-to-right, top-to-bottom).

Any dashboard filters not included in the list are sorted at the end.

hidden_parameters
Array of strings

Responses

Response Schema: application/vnd.api+json
object (Dashboard)
id
string
type
string
Value: "dashboards"
object (DashboardAttributes)
name
string
description