This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Management API

The Management API is a REST API that you can use to view and manage Vertica databases with scripts or applications that accept REST and JSON.

The Management API is a REST API that you can use to view and manage Vertica databases with scripts or applications that accept REST and JSON. The response format for all requests is JSON.

1 - cURL

cURL is a command-line tool and application library used to transfer data to or from a server.

cURL is a command-line tool and application library used to transfer data to or from a server. All API requests sent to a Vertica server must be made with HTTPS.

There are four HTTP requests that can be passed using cURL to call API methods:

  • GET: Retrieves data.

  • PUT: Updates data.

  • POST: Creates new data.

  • DELETE: Deletes data.

Syntax

curl https://<NODE>:5444/

Options

The following is a truncated list of options. For a complete list, see the cURL documentation.

-h --help Lists all available options.
-H --header

Specifies custom headers. This is useful for sending a request that requires a Vertica API key.

Example:

$ curl -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/
-k --insecure

Connects with TLS without validating the database's server certificate.

Example:

$ curl -k https://<NODE>:5444/
-X --request

Specifies a request type, one of the following:

  • GET (default)

  • PUT

  • POST

  • DELETE

Example:

$ curl -X REQUEST https://<NODE>:5444/

2 - General API information

These API calls can interact with either standard Vertica nodes or Management Console nodes.

These API calls can interact with either standard Vertica nodes or Management Console nodes.

GET / Returns the agent-specific information useful for version checking and service discovery.
GET api Returns a list of api objects and properties.

2.1 - GET /

Returns API version information and a list of links to child resources for the Management API.

Returns API version information and a list of links to child resources for the Management API.

Resource URL

https://<NODE>:5444/

Authentication

Not required.

Parameters

None.

Example request

GET https://<NODE>:5444/

Response:

{
    "body": {
        "mime-types": [
            "default",
            "application/vertica.database.configuration.json-v2",
            "application/json",
            "application/vertica.nodes.json-v2",
            "default",
            "application/json",
            "default",
            "application/json",
            "application/vertica.jobs.json-v2",
            "default",
            "application/vertica.hosts.json-v2",
            "application/json",
            "default",
            "application/vertica.hosts.json-v2",
            "application/json",
            "default",
            "application/json",
            "application/vertica.host.json-v2",
            "default",
            "application/vertica.hosts.json-v2",
            "application/json",
            "application/vertica.nodes.json-v2",
            "default",
            "application/json",
            "default",
            "application/json",
            "application/vertica.database.json-v2",
            "default",
            "application/vertica.hosts.json-v2",
            "application/json",
            "default",
            "application/vertica.hosts.json-v2",
            "application/json",
            "default",
            "application/json",
            "application/vertica.databases.json-v2",
            "application/vertica.nodes.json-v2",
            "default",
            "application/json",
            "application/vertica.agent.json-v2",
            "default",
            "application/json",
            "default",
            "application/vertica.users.json-v2",
            "application/json"
        ],
        "version": "7.1.0"
    },
    "href": "/",
    "links": [
        "/databases",
        "/hosts",
        "/nodes",
        "/licenses",
        "/webhooks",
        "/backups",
        "/restore",
        "/jobs"
    ],
    "mime-type": "application/vertica.agent.json-v2"
}

2.2 - GET api

Lists all Management API commands, with a brief description of each one and its parameters.

Lists all Management API commands, with a brief description of each one and its parameters.

Resource URL

https://node-ip-address:5444/api

Authentication

None

Example

$ curl -k https://10.20.100.247:5444/api
[
   {
      "route": "/",
      "method": "GET",
      "description": "Returns the agent specific information useful for version checking and service discovery",
      "accepts": {},
      "params": []
   },
   {
      "route": "/api",
      "method": "GET",
      "description": "build the list of cluster objects and properties and return it as a JSON formatted array",
      "accepts": {},
      "params": []
   },
   {
      "route": "/backups",
      "method": "GET",
      "description": "list all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the /opt/vertica/config directory.",
      "accepts": {},
      "params": []
   },
   {
      "route": "/backups/:config_script_base",
      "method": "POST",
      "description": "create a new backup as defined by the given vbr configuration script base (filename minus the .ini extenstion)",
      "accepts": {},
      "params": []
   },
   {
      "route": "/backups/:config_script_base/:archive_id",
      "method": "GET",
      "description": "get the  detail for a specific backup archive",
      "accepts": {},
      "params": []
   },
   {
      "route": "/backups/:config_script_base/:archive_id",
      "method": "DELETE",
      "description": "delete a backup based on the config ini file script",
      "accepts": {},
      "params": []
   },
   {
      "route": "/databases",
      "method": "GET",
      "description": "build the list of databases, their properties, and current status (from cache) and return it as a JSON formatted array",
      "accepts": {},
      "params": []
   },
   {
      "route": "/databases",
      "method": "POST",
      "description": "Create a new database by supplying a valid set of parameters",
      "accepts": {},
      "params": [
         "name    : name of the database to create",
         "passwd  : password used by the database administrative user",
         "only    : optional list of hostnames to include in database",
         "exclude : optional list of hostnames to exclude from the database",
         "catalog : directory used for the vertica catalog",
         "data    : directory used for the initial vertica storage location",
         "port    : port the database will listen on (default 5433)",
         "restart_policy : (optional) set restart policy",
         "force_cleanup_on_failure : (optional) Force removal of existing directories on failure of command",
         "force_removal_at_creation : (optional)  Force removal of existing directories before creating the database",
         "communal_storage_url : (optional) communal storage location for the database",
         "num_shards : (optional) number of shared for databases with communal storage",
         "depot_path : (optional, but if specified requires depot_size) path to a directory where files from communal storage can be locally cached",
         "depot_size : (optional, required by depot_path) size of the depot. Examples: (\"10G\", \"2000M\", \"1T\", \"250K\")",
         "aws_access_key_id: (optional)",
         "aws_secret_access_key : (optional)",
         "configuration_parameters : (optional) A string that is a serialized python-literal dictionary of configuration parameters set at bootstrap.
         '{\"kerberosservicename\":\"verticakerb\"}'"]
   },
   {
      "route": "/databases/:database_name",
      "method": "GET",
      "description": "Retrieve the database properties structure",
      "accepts": {},
      "params": []
   },
   {
      "route": "/databases/:database_name",
      "method": "PUT",
      "description": "Control / alter a database values using the PUT http method",
      "accepts": {},
      "params": ["action : value one of start|stop|rebalance|wla"]
   },
   {
      "route": "/databases/:database_name",
      "method": "DELETE",
      "description": "Delete an existing database",
      "accepts": {},
      "params": []
   },
   {
      "route": "/databases/:database_name/configuration",
      "method": "GET",
      "description": "retrieve the current parameters from the database. if its running return 503 Service Unavailable",
      "accepts": {},
      "params": [
         "user_id  : vertica database username",
         "passwd   : vertica database password"]
   },
   {
      "route": "/databases/:database_name/configuration",
      "method": "PUT",
      "description": "set a list of  parameters in the database. if its not running return 503 Service Unavailable",
      "accepts": {},
      "params": [
         "user_id   : vertica database username",
         "passwd    : vertica database password",
         "parameter : value  vertica parameter/key combo"]
   },
   ...
   {
      "route": "/webhooks/subscribe",
      "method": "POST",
      "description": "post a request with a callback url to subscribe to events from this agent.  Returns a subscription_id that can be used to unsubscribe from the service.  @returns  subscription_id",
      "accepts": {},
      "params": ["url : full url to the callback resource"]
   }
]

3 - Rest APIs for the agent

These API calls interact with standard Vertica nodes.

These API calls interact with standard Vertica nodes.

Backup and restore

GET backups Returns all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the /opt/vertica/config directory.
POST backups/:config_script_base Creates a new backup as defined by the given vbr configuration script base (filename without the .ini extension).
GET backups/:config_script_base/:archive_id Returns details for a specific backup archive.
POST restore/:archive_id Restores a backup.

Databases

GET databases Returns a list of databases, their properties, and current status.
POST databases Creates a new database by supplying a valid set of parameters.
GET databases/:database_name Returns details about a specific database.
PUT databases/:database_name Starts, stops, rebalances, or runs Workload Analyzer on a database.
DELETE databases/:database_name Deletes an existing database.
GET databases/:database_name/configuration Returns the current configuration parameters from the database.
PUT databases/:database_name/configuration Sets one or more configuration parameters in the database.
GET databases/:database_name/hosts Returns hosts details for a specific database.
POST databases/:database_name/hosts Adds a new host to the database.
DELETE databases/:database_name/hosts/:host_id Removes a host from the database.
POST databases/:database_name/hosts/:host_id/process Starts the database process on a specific host.
DELETE databases/:database_name/hosts/:host_id/process Stops the database on a specific host.
POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new Replaces a host with a standby host in the database.
GET databases/:database_name/license Returns the Vertica license that the specified database is using.
GET databases/:database_name/licenses Returns all the feature licenses that the specified database is using.
GET databases/:database_name/nodes Returns a list of nodes for the specified database.
GET databases/:database_name/nodes/:node_id Returns details on a specific node for the specified database.
POST databases/:database_name/process Starts the specified database.
GET databases/:database_name/process Returns the state of the database as either UP or DOWN.
DELETE databases/:database_name/process Stops the specified database on all hosts.
POST databases/:database_name/rebalance/process Rebalances the specified database. This option can have a long run time.
GET databases/:database_name/status [broken] Retrieves the database properties structure.
POST databases/:database_name/Workload Analyzer/process Runs the analyze workload action against the specified database.This option can have a long run time.

Hosts

GET hosts Returns a list of hosts in this cluster.
GET hosts/:hostid Returns details for a specific host in this cluster.

Jobs

GET jobs Returns a list of jobs the agent is tracking, along with their current status and exit codes.
GET jobs/:id Returns the details (the saved output) for a specific job.

Licenses

POST licenses Uploads and applies a new license to this cluster.
GET licenses Returns the license field that databases created on this cluster use.

Nodes

GET nodes Returns a list of nodes in this cluster.
GET nodes/:nodeid Returns details for a specific node in this cluster.

Webhooks

GET webhooks Returns a list of active webhooks.
POST webhooks/subscribe Creates a new webhook.
DELETE webhooks/:subscriber_id Deletes an existing webhook.

3.1 - VerticaAPIKey

The Management API requires an authentication key, named VerticaAPIKEY, to access some API resources.

The Management API requires an authentication key, named VerticaAPIKEY, to access some API resources. You can manage API keys by using the apikeymgr command-line tool.

usage: apikeymgr [-h] [--user REQUESTOR] [--app APPLICATION] [--delete]
                 [--create] [--update] [--migrate]
                 [--secure {restricted,normal,admin}] [--list]

API key management tool

optional arguments:
  -h, --help            show this help message and exit
  --user REQUESTOR      The name of the person requesting the key
  --app APPLICATION     The name of the application that will use the key
  --delete              Delete the key for the given R & A
  --create              Create a key for the given R & A
  --update              Update a key for the given R & A
  --migrate             migrate the keyset to the latest format
  --secure {restricted,normal,admin}
                        Set the keys security level
  --list                List all the keys known

Example request

To create a new VerticaAPIKEY for the dbadmin user with admin access, enter the following:

$ apikeymgr --user dbadmin --app vertica --create --secure admin

Response:

Requestor  : dbadmin
Application: vertica
API Key    : ValidAPIKey
Synchronizing cluster...

3.2 - Backup and restore

You can use these API calls to perform backup and restore tasks for your database.

You can use these API calls to perform backup and restore tasks for your database.

GET backups Returns all the backups that have been created for all vbr configuration files ( *.ini ) that are located in the /opt/vertica/config directory.
POST backups/:config_script_base Creates a new backup as defined by the given vbr configuration script base (filename without the .ini extension).
GET backups/:config_script_base/:archive_id Returns details for a specific backup archive.
POST restore/:archive_id Restores a backup.

3.2.1 - GET backups

Returns a list of all backups created for vbr configuration (*.ini) files that reside in /opt/vertica/config and provides details about each backup.

Returns a list of all backups created for vbr configuration (*.ini) files that reside in /opt/vertica/config and provides details about each backup.

Resource URL

https://<NODE>:5444/backups

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/backups

Response:

{
    "data": [
        {
            "backups": [
                {
                    "archive_id": "v_vdb_bk_snapshot_20190305_174428",
                    "version": "v9.2.1-20190305",
                    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190305_174428",
                    "exclude_patterns": "",
                    "backup_type": "full",
                    "include_patterns": "",
                    "epoch": "16",
                    "objects": "",
                    "hosts": "v_vdb_bk_node0001(10.20.91.240), v_vdb_bk_node0002(10.20.91.241), v_vdb_bk_node0003(10.20.91.242), v_vdb_bk_node0004(10.20.91.243), v_vdb_bk_node0005(10.20.91.244)"
                },
                {
                    "archive_id": "v_vdb_bk_snapshot_20190305_174025",
                    "version": "v9.2.1-20190305",
                    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190305_174025",
                    "exclude_patterns": "",
                    "backup_type": "full",
                    "include_patterns": "",
                    "epoch": "16",
                    "objects": "",
                    "hosts": "v_vdb_bk_node0001(10.20.91.240), v_vdb_bk_node0002(10.20.91.241), v_vdb_bk_node0003(10.20.91.242), v_vdb_bk_node0004(10.20.91.243), v_vdb_bk_node0005(10.20.91.244)"
                }
            ],
            "config_file": "/opt/vertica/config/fullbk.ini",
            "config_script_base": "fullbk",
            "num_backups": 2
        }
    ],
    "href": "/backups",
    "mime-type": "application/vertica.databases.json-v2"
}

3.2.2 - POST backups/:config_script_base

Creates a new backup job for the backup defined in the vbr configuration script :config_script_base.

Creates a new backup job for the backup defined in the vbr configuration script :config_script_base. The vbr configuration script must reside in /opt/vertica/configuration. The :config_script_base value does not include the .ini filename extention.

To determine valid :config_script_base values, see GET backups.

Returns a job ID that you can use to determine the status of the job.

Resource URL

https://<NODE>:5444/backups/:config_script_base

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

POST https://<NODE>:5444/backups/backup3

Response:

{
    "id": "CreateBackup-VMart-1404750602.03",
    "url": "/jobs/CreateBackup-VMart-1404750602.03"
}

3.2.3 - GET backups/:config_script_base/:archive_id

Returns details on a specific backup.

Returns details on a specific backup. You must provide the :config_script_base. This value is the name of a vbr config file (without the .ini filename extension) that resides in /opt/vertica/config. The :archive_id is the value of the backup field that the GET backups command returns.

Resource URL

https://<NODE>:5444/backups/:config_script_base/:archive_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/backups/fullbk/v_vdb_bk_snapshot_20190304_204814

Response:

{
    "archive_id": "v_vdb_bk_snapshot_20190304_204814",
    "config_file": "/opt/vertica/config/fullbk.ini",
    "objects": "",
    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190304_204814",
    "exclude_patterns": "",
    "epoch": "16",
    "include_patterns": "",
    "backup_type": "full",
    "version": "v9.2.1-20190304",
    "hosts": "v_vdb_bk_node0001(10.20.91.240),
             v_vdb_bk_node0002(10.20.91.241),
             v_vdb_bk_node0003(10.20.91.242),
             v_vdb_bk_node0004(10.20.91.243),
             v_vdb_bk_node0005(10.20.91.244)"
}

3.2.4 - POST restore/:archive_id

Creates a new restore job to restore the database from the backup archive identified by :archive_id.

Creates a new restore job to restore the database from the backup archive identified by :archive_id. The :archive_id is the value of a backup field that the GET backups command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/restore/:archive_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

POST https://<NODE>:5444/restore/backup3_20140707_132904

Response:

{
    "id": "RestoreBackup-VMart-1404760113.71",
    "url": "/jobs/RestoreBackup-VMart-1404760113.71"
}

3.3 - Databases

You can use these API calls to interact with your database.

You can use these API calls to interact with your database.

GET databases Returns a list of databases, their properties, and current status.
POST databases Creates a new database by supplying a valid set of parameters.
GET databases/:database_name Returns details about a specific database.
PUT databases/:database_name Starts, stops, rebalances, or runs Workload Analyzer on a database.
DELETE databases/:database_name Deletes an existing database.
GET databases/:database_name/configuration Returns the current configuration parameters from the database.
PUT databases/:database_name/configuration Sets one or more configuration parameters in the database.
GET databases/:database_name/hosts Returns hosts details for a specific database.
POST databases/:database_name/hosts Adds a new host to the database.
DELETE databases/:database_name/hosts/:host_id Removes a host from the database.
POST databases/:database_name/hosts/:host_id/process Starts the database process on a specific host.
DELETE databases/:database_name/hosts/:host_id/process Stops the database on a specific host.
POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new Replaces a host with a standby host in the database.
GET databases/:database_name/license Returns the Vertica license that the specified database is using.
GET databases/:database_name/licenses Returns all the feature licenses that the specified database is using.
GET databases/:database_name/nodes Returns a list of nodes for the specified database.
GET databases/:database_name/nodes/:node_id Returns details on a specific node for the specified database.
POST databases/:database_name/process Starts the specified database.
GET databases/:database_name/process Returns the state of the database as either UP or DOWN.
DELETE databases/:database_name/process Stops the specified database on all hosts.
POST databases/:database_name/rebalance/process Rebalances the specified database. This option can have a long run time.
GET databases/:database_name/status [broken] Retrieves the database properties structure.
POST databases/:database_name/Workload Analyzer/process Runs the analyze workload action against the specified database.This option can have a long run time.

3.3.1 - GET databases

Returns a list of databases, their current status, and database properties.

Returns a list of databases, their current status, and database properties.

Resource URL

https://<NODE>:5444/databases

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/databases

An example of the full request using cURL:

curl -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/databases

Response:

{
    "body": [
        {
            "href": "/databases/VMart",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "VMart",
            "port": "5433",
            "status": "UP"
        },
        {
            "href": "/databases/testDB",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "testDB",
            "port": "5433",
            "status": "DOWN"
        }
    ],
    "href": "/databases",
    "links": [
        "/:database_name"
    ],
    "mime-type": "application/vertica.databases.json-v2"
}

3.3.2 - POST databases

Creates a job to create a new database with the provided parameters.

Creates a job to create a new database with the provided parameters.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

name Name of the database to create.
passwd Password for the new database.
only Optional list of hostnames to include in the database. By default, all nodes in the cluster are added to the database.
exclude Optional list of hostnames to exclude from the database.
catalog Path of the catalog directory.
data Path of the data directory.
port Port where the database listens for client connections. Default is 5433.

Example request

POST
https://:5444/databases?passwd=db_password&name=db_name&
catalog=%2Fpath%2Fto%2Fcatalog&data=%2Fpath%2Fto%2Fdata_directory

Response:

{
    "jobid": "CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "resource": "/jobs/CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "userid": "dbadmin"
}

3.3.3 - GET databases/:database_name

Returns details about a specific database.

Returns details about a specific database. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/databases/VMart

Response:

{
    "body": {
        "database_id": "VMart",
        "id": "VMart",
        "nodes": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "nodes_new": [
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.247",
                "id": "v_vmart_node0001"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.248",
                "id": "v_vmart_node0002"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.249",
                "id": "v_vmart_node0003"
            }
        ],
        "path": "/home/dbadmin/VMart",
        "port": "5433",
        "restartpolicy": "ksafe",
        "status": "UP"
    },
    "href": "/databases/VMart",
    "links": [
        "/configuration",
        "/hosts",
        "/license",
        "/nodes",
        "/process",
        "/rebalance/process",
        "/status",
        "/Workload Analyzer/process"
    ],
    "mime-type": "application/vertica.database.json-v2"
}

3.3.4 - PUT databases/:database_name

Creates a job to run the action specified by the action parameter against the database identified by :database_name.

Creates a job to run the action specified by the action parameter against the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have normal level security or higher.

Parameters

user_id A database username.
passwd A password for the username.
action

Can be one of the following values:

  • start — Start the database.

  • stop — Stop the database.

  • rebalance — Rebalance the database.

  • Workload Analyzer — Run Work Load Analyzer against the database.

Example request

PUT https://:5444/databases/testDB?user_id=username&passwd=username_password&action=stop

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:28:49.321744",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:28:49.321744"
}

3.3.5 - DELETE databases/:database_name

Creates a job to delete (drop) an existing database on the cluster.

Creates a job to delete (drop) an existing database on the cluster. To perform this operation, you must first stop the database. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

None.

Example request

DELETE https://<NODE>:5444/databases/TestDB

Response:

{
    "id": "DropDatabase-TestDB-2014-07-18 12:50:33.332383",
    "url": "/jobs/DropDatabase-TestDB-2014-07-18 12:50:33.332383"
}

3.3.6 - GET databases/:database_name/configuration

Returns a list of configuration parameters for the database identified by :database_name.

Returns a list of configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd The password for the username.

Example request

GET https://:5444/databases/testDB/configuration?user_id=username&passwd=username_password

Response:

This API call returns over 100 configuration parameters.. The following response is a small subset of the total amount returned.

[
    {
        "node_name": "ALL",
        "parameter_name": "ACDAlgorithmForSynopsisVersion1",
        "current_value": "1",
        "restart_value": "1",
        "database_value": "1",
        "default_value": "1",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Algorithm used to interpret synopsis version 1 for approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDLinearCountThreshold",
        "current_value": "-1.000000",
        "restart_value": "-1.000000",
        "database_value": "-1.000000",
        "default_value": "-1.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "If positive, will overwrite the default linear counting threshold in approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDSynopsisVersion",
        "current_value": "2",
        "restart_value": "2",
        "database_value": "2",
        "default_value": "2",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Default synopsis version to be generated by approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AHMBackupManagement",
        "current_value": "0",
        "restart_value": "0",
        "database_value": "0",
        "default_value": "0",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "NODE, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Consider backup epochs when setting new AHM"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ARCCommitPercentage",
        "current_value": "3.000000",
        "restart_value": "3.000000",
        "database_value": "3.000000",
        "default_value": "3.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "ARC will commit only if the change is more than the percentage specified"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AWSCAFile",
        "current_value": "",
        "restart_value": "",
        "database_value": "",
        "default_value": "",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "f",
        "change_requires_restart": "f",
        "description": "Overrides the default CA file"
    },
    ...
]

3.3.7 - PUT databases/:database_name/configuration

Sets one or more configuration parameters for the database identified by :database_name.

Sets one or more configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns the parameter name, the requested value, and the result of the attempted change (Success or Failed).

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

user_id A database username.
passwd The password for the username.
parameter_name A parameter name and value combination for the parameter to be changed. Values must be URL encoded. You can include multiple name/value pairs to set multiple parameters with a single API call.

Example request

PUT
https://:5444/databases/testDB/configuration?user_id=username&passwd=username_password
&JavaBinaryForUDx=%2Fusr%2Fbin%2Fjava&TransactionIsolationLevel=SERIALIZABLE

Response:

[
    {
        "key": "JavaBinaryForUDx",
        "result": "Success",
        "value": "/usr/bin/java"
    },
    {
        "key": "TransactionIsolationLevel",
        "result": "Success",
        "value": "SERIALIZABLE"
    }
]

3.3.8 - GET databases/:database_name/hosts

Returns the hostname/IP address, node name, and UP/DOWN status of each host associated with the database identified by :database_name.

Returns the hostname/IP address, node name, and UP/DOWN status of each host associated with the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/databases/VMart/hosts

Response:

{
    "body": [
        {
            "hostname": "10.20.100.247",
            "nodename": "v_vmart_node0001",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904191"
        },
        {
            "hostname": "10.20.100.248",
            "nodename": "v_vmart_node0002",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904209"
        },
        {
            "hostname": "10.20.100.249",
            "nodename": "v_vmart_node0003",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904215"
        }
    ],
    "href": "/databases/VMart/hosts",
    "links": [],
    "mime-type": "application/vertica.hosts.json-v2"
}

3.3.9 - POST databases/:database_name/hosts

Creates a job to add a host to the database identified by :database_name.

Creates a job to add a host to the database identified by :database_name. This host must already be part of the cluster. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

user_id A database username.
passwd The password for the username.
hostname The hostname to add to the database. This host must already be part of the cluster.

Example request

POST https://:5444/databases/testDB/hosts?hostname=192.168.232.181&user_id=username&passwd=username_password

Response:

{
    "id": "AddHostToDatabase-testDB-2014-07-20 12:24:04.088812",
    "url": "/jobs/AddHostToDatabase-testDB-2014-07-20 12:24:04.088812"
}

3.3.10 - DELETE databases/:database_name/hosts/:host_id

Creates a job to remove the host identified by :host_id from the database identified by :database_name.

Creates a job to remove the host identified by :host_id from the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

user_id A database username.
passwd A password for the username.

Example request

DELETE https://:5444/databases/testDB/hosts/192.168.232.181?user_id=username&passwd=username_password

Response:

{
    "id": "RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235",
    "url": "/jobs/RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235"
}

3.3.11 - POST databases/:database_name/hosts/:host_id/process

Creates a job to start the vertica process for the database identified by :database_name on the host identified by :host_id.

Creates a job to start the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

POST https://<NODE>:5444/databases/testDB/hosts/192.168.232.181/process

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 13:14:03.968340",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 13:14:03.968340"
}

3.3.12 - GET databases/:database_name/license

Returns details about the database license being used by the database identified by :database_name.

Returns details about the database license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/license

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd The password for the username.

Example request

GET https://:5444/VMart/license?user_id=username&passwd=username_password

Response:

{
    "body": {
        "details": {
            "assigned_to": "Vertica Systems, Inc.",
            "grace_period": 0,
            "is_ce": false,
            "is_unlimited": false,
            "name": "vertica",
            "not_after": "Perpetual",
            "not_before": "2007-08-03"
        },
        "last_audit": {
            "audit_date": "2014-07-18 13:49:22.530105-04",
            "database_size_bytes": "814060522",
            "license_size_bytes": "536870912000",
            "usage_percent": "0.00151630588248372"
        }
    },
    "href": "/databases/VMart/license",
    "links": [],
    "mime-type": "application/vertica.license.json-v2"
}

3.3.13 - GET databases/:database_name/licenses

Returns details about all license being used by the database identified by :database_name.

Returns details about all license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd The password for the username.

Example request

GET https://:5444/VMart/licenses?user_id=username&passwd=username_password

Response:

{
    "body": [
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc.",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "vertica",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:26.318378-04",
                "database_size_bytes": "819066288",
                "license_size_bytes": "536870912000",
                "usage_percent": "0.00152562984824181"
            }
        },
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc., FlexTable",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "com.vertica.flextable",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:25.111312",
                "database_size_bytes": 0,
                "license_size_bytes": 536870912000,
                "usage_percent": 0
            }
        }
    ],
    "href": "/databases/VMart/licenses",
    "links": [],
    "mime-type": "application/vertica.features.json-v2"
}

3.3.14 - DELETE databases/:database_name/hosts/:host_id/process

Creates a job to stop the vertica process for the database identified by :database_name on the host identified by :host_id.

Creates a job to stop the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

DELETE https://<NODE>:5444/databases/testDB/hosts/192.168.232.181/process

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:02:08.453547",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:02:08.453547"
}

3.3.15 - POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new

Creates a job to replace the host identified by hosts/:host_id with the host identified by replace_with/:host_id.

Creates a job to replace the host identified by hosts/:host_id with the host identified by replace_with/:host_id. Vertica performs these operations for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field as returned by GET databases/:database_name. You can find valid replacement hosts using GET hosts. The replacement host cannot already be part of the database. You must stop the vertica process on the host being replaced.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/replace_with/:host_id_new

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

user_id A database username.
passwd A password for the username.

Example request

POST https://:5444/databases/testDB/hosts/192.168.232.180/replace_with/192.168.232.181?user_id=username&passwd=username_password

Response:

{
    "id": "ReplaceNode-testDB-2014-07-20 13:50:28.423509",
    "url": "/jobs/ReplaceNode-testDB-2014-07-20 13:50:28.423509"
}

3.3.16 - GET databases/:database_name/nodes

Returns a comma-separated list of node IDs for the database identified by :database_name.

Returns a comma-separated list of node IDs for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/nodes

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/VMart/nodes

Response:

[
    {
        "database_id": "VMart",
        "node_id": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "status": "Unknown"
    }
]

3.3.17 - GET databases/:database_name/nodes/:node_id

Returns details about the node identified by :node_id.

Returns details about the node identified by :node_id. The :node_id is one of the node IDs returned by GET databases/:database_name/nodes.

Resource URL

https://<NODE>:5444/:database_name/nodes/:node_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/databases/VMart/nodes/v_vmart_node0001

Response:

{
    "db": "VMart",
    "host": "10.20.100.247",
    "name": "v_vmart_node0001",
    "state": "UP"
}

3.3.18 - POST databases/:database_name/process

Creates a job to start the database identified by :database_name.

Creates a job to start the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

epoch Start the database from this epoch.
include Include only these hosts when starting the database. Use a comma-separated list of hostnames.

Example request

POST https://<NODE>:5444/databases/:testDB/process

An example of the full request using cURL:

curl -d "epoch=epoch_number&include=host1,host2" -X POST -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 12:41:46.061408",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 12:41:46.061408"
}

3.3.19 - GET databases/:database_name/process

Returns a state of UP or DOWN for the database identified by :database_name.

Returns a state of UP or DOWN for the database identified by :database_name. The :database_name is the value of the namefield that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/databases/VMart/process

Response:

{
    "state": "UP"
}

3.3.20 - DELETE databases/:database_name/process

Creates a job to stop the database identified by :database_name.

Creates a job to stop the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can useto determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd The password for the username.

Example request

DELETE https://:5444/databases/testDB/process?user_id=username&passwd=username_password

An example of the full request using cURL:

curl -X DELETE -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process?user_id=dbadmin"&"passwd=vertica

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 12:46:04.406637",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 12:46:04.406637"
}

3.3.21 - POST databases/:database_name/rebalance/process

Creates a job to run a rebalance on the database identified by host identified by :database_name.

Creates a job to run a rebalance on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/rebalance/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd A password for the username.

Example request

POST https://:5444/databases/testDB/rebalance/process?user_id=username&passwd=username_password

Response:

{
    "id": "RebalanceData-testDB-2014-07-20 21:42:45.731038",
    "url": "/jobs/RebalanceData-testDB-2014-07-20 21:42:45.731038"
}

3.3.22 - POST databases/:database_name/Workload analyzer/process

Creates a job to run Workload Analyzer on the database identified by host identified by :database_name.

Creates a job to run Workload Analyzer on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/Workload Analyzer/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

user_id A database username.
passwd A password for the username.

Example request

POST https://:5444/databases/testDB/Workload Analyzer/process?user_id=username&passwd=username_password

Response:

{
    "id": "AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989",
    "url": "/jobs/AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989"
}

3.4 - Hosts

You can use these API calls to get information on the hosts in your cluster.

You can use these API calls to get information on the hosts in your cluster.

GET hosts Returns a list of hosts in this cluster.
GET hosts/:hostid Returns details for a specific host in this cluster.

3.4.1 - GET hosts

Returns a list of the hosts in the cluster and the hardware, software, and network details about each host.

Returns a list of the hosts in the cluster and the hardware, software, and network details about each host.

Resource URL

https://<NODE>:5444/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/hosts

Response:

{
    "body": [
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.247",
            "hostname": "v_vmart_node0001.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.247",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.1.x0"
            }
        },
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.248",
            "hostname": "v_vmart_node0002.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.248",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.1.x0"
            }
        },
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.249",
            "hostname": "v_vmart_node0003.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.249",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.1.x0"
            }
        }
    ],
    "href": "/hosts",
    "links": [
        "/:hostid"
    ],
    "mime-type": "application/vertica.hosts.json-v2"
}

3.4.2 - GET hosts/:hostid

Returns hardware, software, and network details about the host identified by :host_id.

Returns hardware, software, and network details about the host identified by :host_id. You can find :host_id for each host using GET hosts.

Resource URL

https://<NODE>:5444/hosts/:hostid

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/hosts/:10.20.100.247

Response:

{
    "body": {
        "cpu_info": {
            "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
            "number_of_cpus": 2
        },
        "hostname": "v_vmart_node0001.example.com",
        "max_user_proc": "3833",
        "nics": [
            {
                "broadcast": "10.20.100.255",
                "ipaddr": "10.20.100.247",
                "name": "eth0",
                "netmask": "255.255.255.0",
                "speed": "unknown"
            },
            {
                "broadcast": "255.255.255.255",
                "ipaddr": "127.0.0.1",
                "name": "lo",
                "netmask": "255.0.0.0",
                "speed": "locallink"
            }
        ],
        "total_memory": 3833,
        "vertica": {
            "arch": "x86_64",
            "brand": "vertica",
            "release": "20140716",
            "version": "24.1.x0"
        }
    },
    "href": "/hosts/10.20.100.247",
    "links": [],
    "mime-type": "application/vertica.host.json-v2"
}

3.5 - Jobs

You can use these API calls to get information on your database's jobs.

You can use these API calls to get information on your database's jobs.

GET jobs Returns a list of jobs the agent is tracking, along with their current status and exit codes.
GET jobs/:id Returns the details (the saved output) for a specific job.

3.5.1 - GET jobs

Returns a list of jobs being tracked by the agent and job details.

Returns a list of jobs being tracked by the agent and job details.

Jobs always start immediately. The is_running field is a Boolean value. If is_running is false, then the job is complete.

The exit_code details the status of the job. The exit_code is different for certain types of jobs:

  • For Backup jobs:

    • 0 indicates success.

    • Any other number indicates a failure.

  • For all other jobs:

    • -9 indicates success.

    • Any other number indicates a failure.

You can see details about failures in /opt/vertica/log/agentStdMsg.log.

Resource URL

https://<NODE>:5444/jobs

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/jobs

Response:

{
    "body": [
        {
            "exit_code": 0,
            "id": "CreateBackup-VMart-1405012447.75",
            "is_running": false,
            "status": "unused",
            "ts": "1405012461.18"
        },
        {
            "exit_code": 1,
            "id": "CreateBackup-VMart-1405012454.88",
            "is_running": false,
            "status": "unused",
            "ts": "1405012455.18"
        }
    ],
    "href": "/jobs",
    "links": [
        "/:jobid"
    ],
    "mime-type": "application/vertica.jobs.json-v2"
}

3.5.2 - GET jobs/:id

Gets the details for a specific job with the provided :id.

Gets the details for a specific job with the provided :id. You can determine the list of job :ids usingGET jobs.

Details for a specific job are the same as the details provided for all jobs byGET jobs.

Resource URL

https://<NODE>:5444/jobs/:id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/jobs/CreateBackup-VMart-1405012454.88

3.6 - Licenses

You can use these API calls to manage licenses for your database.

You can use these API calls to manage licenses for your database.

POST licenses Uploads and applies a new license to this cluster.
GET licenses Returns the license field that databases created on this cluster use.

3.6.1 - POST licenses

Uploads and applies a license file to this cluster.

Uploads and applies a license file to this cluster.

You must provide the license file as an HTTP POST form upload, identified by the name license. For example, you can use cURL:

curl -k --request POST -H "VerticaApiKey:ValidAPIKey" \
https://v_vmart_node0001:5444/licenses --form "license=@vlicense.dat"

Resource URL

https://<NODE>:5444/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

None.

Example request

POST https://<NODE>:5444/licenses

Response:

There is no HTTP body response for successful uploads. A successful upload returns an HTTP 200/OK header.

3.6.2 - GET licenses

Returns any license files that are used by this cluster when creating databases.

Returns any license files that are used by this cluster when creating databases. License files must reside in /opt/vertica/config/share.

Resource URL

https://<NODE>:5444/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/licenses

Response:

{
    "body": [
        {
            "comment": "Vertica license is valid",
            "end": "Perpetual",
            "grace": "0",
            "size": "1TB CE Nodes 3",
            "start": "2011-11-22",
            "status": true,
            "vendor": "Vertica Community Edition"
        }
    ],
    "href": "/license",
    "links": [],
    "mime-type": "application/vertica.license.json-v2"
}

3.7 - Nodes

You can use these API calls to retrieve information on the nodes in your cluster.

You can use these API calls to retrieve information on the nodes in your cluster.

GET nodes Returns a list of nodes in this cluster.
GET nodes/:nodeid Returns details for a specific node in this cluster.

3.7.1 - GET nodes

Returns a list of nodes associated with this cluster.

Returns a list of nodes associated with this cluster.

Resource URL

https://<NODE>:5444/nodes

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/nodes

Response:

{
    "body": [
        "node0001",
        "node0002",
        "node0003",
        "v_testdb_node0001",
        "v_testdb_node0002",
        "v_testdb_node0003",
        "v_vmart_node0001",
        "v_vmart_node0002",
        "v_vmart_node0003"
    ],
    "href": "/nodes",
    "links": [
        "/:nodeid"
    ],
    "mime-type": "application/vertica.nodes.json-v2"
}

3.7.2 - GET nodes/:nodeid

Returns details about the node identified by :node_id.

Returns details about the node identified by :node_id. You can find the :node_id for each node using GET nodes.

In the body field, the following information is detailed in comma-separated format:

  • Node Name

  • Host Address

  • Catalog Directory

  • Data Directory

Resource URL

https://<NODE>:5444/nodes/:node_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/nodes/v_vmart_node0001

Response:

{
    "body": [
        "v_vmart_node0001",
        "10.20.100.247,/home/dbadmin,/home/dbadmin"
    ],
    "href": "/nodes/v_vmart_node0001",
    "links": [],
    "mime-type": "application/vertica.node.json-v2"
}

3.8 - Webhooks

You can use these API calls to obtain information on, create, or delete webhooks.

You can use these API calls to obtain information on, create, or delete webhooks.

GET webhooks Returns a list of active webhooks.
POST webhooks/subscribe Creates a new webhook.
DELETE webhooks/:subscriber_id Deletes an existing webhook.

3.8.1 - GET webhooks

Returns a list of active webhooks for this cluster.

Returns a list of active webhooks for this cluster.

Resource URL

https://<NODE>:5444/webhooks

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

GET https://<NODE>:5444/webhooks

Response:

{
    "body": [
        {
            "host": "192.168.232.1",
            "id": "79c1c8a18be02804b3d2f48ea6462909",
            "port": 80,
            "timestamp": "2014-07-20 22:54:09.829642",
            "url": "/gettest.htm"
        },
        {
            "host": "192.168.232.1",
            "id": "9c32cb0f3d2f9a7cb10835f1732fd4a7",
            "port": 80,
            "timestamp": "2014-07-20 22:54:09.829707",
            "url": "/getwebhook.php"
        }
    ],
    "href": "/webhooks",
    "links": [
        "/subscribe",
        "/:subscriber_id"
    ],
    "mime-type": "application/vertica.webhooks.json-v2"
}

3.8.2 - POST webhooks/subscribe

Creates a subscription for a webhook.

Creates a subscription for a webhook.

Resource URL

https://<NODE>:5444/webhooks/subscribe

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

url A URL to an application that accepts JSON messages from this cluster.

Example request

POST https://:5444//webhooks/subscribe?url=http%3A%2F%2Fexample.com%2Fgetwebhook.php

Response:

The response is not JSON encoded. The only text response is the ID of the webhook subscription. Additionally, an HTTP 200/OK header indicates success.

79c1c8a18be02804b3d2f48ea6462909

3.8.3 - DELETE webhooks/:subscriber_id

Deletes the webhook identified by :subscriber_id.

Deletes the webhook identified by :subscriber_id. The :subscriber_id is the value of the id field that the GET webhooks command returns.

Resource URL

https://<NODE>:5444/webhooks/:subscriber_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

DELETE https://<NODE>:5444/webhooks/79c1c8a18be02804b3d2f48ea6462909

Response:

There is no HTTP body response for successful deletes. A successful delete returns an HTTP 200/OK header.

4 - Rest APIs for the Management Console

These API calls interact with Management Console nodes.

These API calls interact with Management Console nodes.

Alerts

GET alerts Returns alerts for the current user.

Time information

GET mcTimeInfo Returns the current time for the MC server and the timezone of the location where the MC server is located.

4.1 - MC-User-ApiKey

The MC-User-ApiKey is a user-specific key used with Management Console.

The MC-User-ApiKey is a user-specific key used with Management Console. Users must have an MC-User-ApiKey to interact with MC using the Rest API. All users with roles other than None automatically receive an MC-User-ApiKey.

This key grants users the same rights through the API that they have available through their MC roles. To interact with the MC, users pass the key in the request header for the API.

View the MC-User-ApiKey

If you are the database administrator, you can view the MC-User-ApiKey for all users. Individual users can view their own keys.

  1. Connect to MC and go to MC Settings > User Management.

  2. Select the user to view and click Edit. The user's key appears in the User API Key field.

4.2 - GET alerts

Returns a list of MC alerts, their current status, and database properties.

Returns a list of MC alerts, their current status, and database properties.

Resource URL

https://<MC_NODE>:5450/webui/api/alerts

Authentication

Requires an MC-User-Apikey in the request header.

Filter parameters

types

The type of alert to retrieve. Valid values are:

  • info

  • notice

  • warning

  • error

  • critical

  • alert

  • emergency

category For information, see Thresholds category filter.
db_name For information, see Database name category filter.
limit The maximum number of alerts to retrieve. If the limit is lower than the number of existing alerts, Vertica retrieves the most recent alerts. Used with the type parameter, Vertica retrieves up to the limit for each type. For example, for a limit of five and types of critical and emergency, you could receive up to ten total alerts.
time_from

The timestamp start point from which to retrieve alerts. You can use this parameter in combination with the time_to parameter to retrieve alerts for a specific time range. Values must be passed in the following format: yyyy-MM-ddTHH:mm.

If you provide only the time_from parameter, and omit the time_to parameter, the response contains all alerts generated from the time_from parameter to the current time.

time_to

The timestamp end point from which to retrieve alerts. You can use this parameter in combination with the time_from parameter to retrieve alerts for a specific time range. Values must be passed in the following format: yyyy-MM-ddTHH:mm.

If you provide only the time_to parameter, and omit the time_from parameter, the response contains all alerts generated from the earliest possible time to the time passed in time_to.

Example request

GET https://<MC_NODE>:5450/webui/api/alerts?types=critical

Request alerts using cURL

This example shows how you can request alerts using cURL. In this example, the limit parameter is set to '2' and the types parameters is set to info and notice:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?limit=2&types=info,notice

Response:

[
   {
      "alerts":[
         {
            "id":5502,
            "markedRead":false,
            "eventTypeCode":0,
            "create_time":"2016-02-02 05:12:10.0",
            "updated_time":"2016-02-02 15:50:20.511",
            "severity":"warning",
            "status":1,
            "nodeName":"v_vmart_node0001",
            "databaseName":"VMart",
            "databaseId":1,
            "clusterName":"1449695416208_cluster",
            "description":"Warning: Low disk space detected (73% in use)",
            "summary":"Low Disk Space",
            "internal":false,
            "count":3830
         },
         {
            "id":5501,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2016-02-02 05:12:02.31",
            "updated_time":"2016-02-02 05:12:02.31",
            "severity":"notice",
            "status":1,
            "databaseName":"VMart",
            "databaseId":1,
            "clusterName":"1449695416208_cluster",
            "description":"Analyze Workload operation started on Database",
            "summary":"Analyze Workload operation started on Database",
            "internal":false,
            "count":1
         }
      ],
      "total_alerts":190,
      "request_query":"limit=2",
      "request_time":"2016-02-02 15:50:26 -0500"
   }
]

Request alerts within a time range

These examples show various ways in which you can request the same alert as in the preceding example, but within specified time ranges.

Request the alert within a specific time range, using the time_from and time_to parameters:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?types=info,notice&time_from=2016-01-01T12:12&time_to=2016-02-01T12:12

Request the alert from a specific start time to the present using the time_from parameter:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?types=info,notice&time_from=2016-01-01T12:12

Request the alert to a specific end point using the time_to parameter. When you use the time_to parameter without the time_from parameter, the time_from parameter defaults to the oldest alerts your MC contains:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?types=info,notice&time_to=2016-01-01T12:12

4.3 - GET mcTimeInfo

Returns the current time for the MC server and the timezone where the MC server is located.

Returns the current time for the MC server and the timezone where the MC server is located.

Resource URL

https://<MC_NODE>:5450/webui/api/mcTimeInfo

Authentication

Requires an MC-User-Apikey in the request header.

Parameters

None.

Example request

GET https://<MC_NODE>:5450/webui/api/mcTimeInfo

This example shows how you can request MC time information using cURL:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/mcTimeInfo

Response:

{"mc_current_time":"Tue, 2000-01-01 01:02:03 -0500","mc_timezone":"US/Eastern"}

4.4 - Thresholds category filter

Returns a list of alerts related to threshold settings in MC.

Returns a list of alerts related to threshold settings in MC.

Resource URL

https://<MC_NODE>:5450/webui/api/alerts?category=thresholds

Authentication

Requires an MC-User-Apikey in the request header.

Example request

GET https://<MC_NODE>:5450/webui/api/alerts?category=thresholds

This example shows how you can request alerts on thresholds using cURL:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?category=thresholds

Response:


 [
   {
      "alerts":[
         {
            "id":33,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-10 10:28:41.332",
            "updated_time":"2015-11-10 10:28:41.332",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":" Database: mydb Lower than threshold Node Disk I/O 10 %   v_mydb_node0002 ;1.6%  v_mydb_node0002 ;1.4%  v_mydb_node0002 ;2.3%  v_mydb_node0002 ;1.13%  v_mydb_node0002 ;1.39%  v_mydb_node0001 ;3.78%  v_mydb_node0003 ;1.79%  ",
            "summary":"Threshold : Node Disk I/O < 10 %",
            "internal":false,
            "count":1
         },
         {
            "id":32,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-10 10:28:40.975",
            "updated_time":"2015-11-10 10:28:40.975",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":" Database: mydb Lower than threshold Node Memory 10 %   v_mydb_node0002 ;5.47%  v_mydb_node0002 ;5.47%  v_mydb_node0002 ;5.47%  v_mydb_node0002 ;5.47%  v_mydb_node0002 ;5.48%  v_mydb_node0003 ;4.53%  ",
            "summary":"Threshold : Node Memory < 10 %",
            "internal":false,
            "count":1
         },
         {
            "id":31,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-10 10:28:40.044",
            "updated_time":"2015-11-10 10:28:40.044",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":" Database: mydb Lower than threshold Node CPU 10 %   v_mydb_node0002 ;1.4%  v_mydb_node0002 ;1.64%  v_mydb_node0002 ;1.45%  v_mydb_node0002 ;2.49%  ",
            "summary":"Threshold : Node CPU < 10 %",
            "internal":false,
            "count":1
         },
         {
            "id":30,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-10 10:28:34.562",
            "updated_time":"2015-11-10 10:28:34.562",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":" Database: mydb Exceed threshold Node Disk Usage 60 %   v_mydb_node0001 ;86.41%  ",
            "summary":"Threshold : Node Disk Usage > 60 %",
            "internal":false,
            "count":1
         }
      ],
      "total_alerts":4,
      "request_query":"category=thresholds",
      "request_time":"2015-11-10 10:29:17.129"
   }
]

See also

4.5 - Database name category filter

Returns a list of MC alerts for a specific database.

Returns a list of MC alerts for a specific database.

Resource URL

https://<MC_NODE>:5450/webui/api/alerts?db_name=

Authentication

Requires an MC-User-Apikey in the request header.

Example request

GET https://<MC_NODE>:5450/webui/api/alerts?db_name=database_name

This example shows how you can view alerts on a specific database using cURL:

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?db_name="mydb"

Response:

[
   {
      "alerts":[
         {
            "id":9,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 15:10:53.391",
            "updated_time":"2015-11-05 15:10:53.391",
            "severity":"notice",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Workload analyzed successfully",
            "summary":"Analyze Workload operation has succeeded on Database",
            "internal":false,
            "count":1
         },
         {
            "id":8,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 15:10:31.16",
            "updated_time":"2015-11-05 15:10:31.16",
            "severity":"notice",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Analyze Workload operation started on Database",
            "summary":"Analyze Workload operation started on Database",
            "internal":false,
            "count":1
         },
         {
            "id":7,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 00:15:00.204",
            "updated_time":"2015-11-05 00:15:00.204",
            "severity":"alert",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Workload analyzed successfully",
            "summary":"Analyze Workload operation has succeeded on Database",
            "internal":false,
            "count":1
         },
         {
            "id":6,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-04 15:14:59.344",
            "updated_time":"2015-11-04 15:14:59.344",
            "severity":"notice",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Workload analyzed successfully",
            "summary":"Analyze Workload operation has succeeded on Database",
            "internal":false,
            "count":1
         },
         {
            "id":5,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-04 15:14:38.925",
            "updated_time":"2015-11-04 15:14:38.925",
            "severity":"notice",
            "status":1,
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Analyze Workload operation started on Database",
            "summary":"Analyze Workload operation started on Database",
            "internal":false,
            "count":1
         },
         {
            "id":4,
            "markedRead":false,
            "eventTypeCode":0,
            "create_time":"2015-11-04 15:14:33.0",
            "updated_time":"2015-11-05 16:26:17.978",
            "severity":"notice",
            "status":1,
            "nodeName":"v_mydb_node0001",
            "databaseName":"lmydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Workload analyzed successfully",
            "summary":"Analyze Workload operation has succeeded on Database",
            "internal":false,
            "count":1
         },
         {
            "id":3,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-04 15:14:32.806",
            "updated_time":"2015-11-04 15:14:32.806",
            "severity":"info",
            "status":1,
            "hostIp":"10.20.100.64",
            "nodeName":"v_mydb_node0003",
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Agent status is UP on IP 127.0.0.1",
            "summary":"Agent status is UP on IP 127.0.0.1",
            "internal":false,
            "count":1
         },
         {
            "id":2,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-04 15:14:32.541",
            "updated_time":"2015-11-04 15:14:32.541",
            "severity":"info",
            "status":1,
            "hostIp":"10.20.100.63",
            "nodeName":"v_mydb_node0002",
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Agent status is UP on IP 127.0.0.1",
            "summary":"Agent status is UP on IP 127.0.0.1",
            "internal":false,
            "count":1
         },
         {
            "id":1,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-04 15:14:32.364",
            "updated_time":"2015-11-04 15:14:32.364",
            "severity":"info",
            "status":1,
            "hostIp":"10.20.100.62",
            "nodeName":"v_mydb_node0001",
            "databaseName":"mydb",
            "databaseId":1,
            "clusterName":"1446668057043_cluster",
            "description":"Agent status is UP on IP 127.0.0.1",
            "summary":"Agent status is UP on IP 127.0.0.1",
            "internal":false,
            "count":1
         }
      ],
      "total_alerts":9,
      "request_query":"db_name=mydb",
      "request_time":"2015-11-05 16:26:21.679"
   }
]

4.6 - Combining sub-category filters with category filters

You can combine category filters with sub-category filters, to obtain alert messages for specific thresholds you set in MC.

You can combine category filters with sub-category filters, to obtain alert messages for specific thresholds you set in MC. You can also use sub-category filters to obtain information about alerts on specific resource pools in your database.

Sub-category filters

You can use the following sub-category filters with the category filters. Sub-category filters are case sensitive and must be lowercase.

Sub-Category Filter Alerts Related to Threshold Value Set For:
THRESHOLD_NODE_CPU Node CPU
THRESHOLD_NODE_MEMORY Node Memory
THRESHOLD_NODE_DISK_USAGE Node Disk Usage
THRESHOLD_NODE_DISKIO Node Disk I/O
THRESHOLD_NODE_CPUIO Node CPU I/O Wait
THRESHOLD_NODE_REBOOTRATE Node Reboot Rate
THRESHOLD_NETIO Network I/O Error
THRESHOLD_QUERY_QUEUED Queued Query Number
THRESHOLD_QUERY_FAILED Failed Query Number
THRESHOLD_QUERY_SPILLED Spilled Query Number
THRESHOLD_QUERY_RETRIED Retried Query Number
THRESHOLD_QUERY_RUNTIME Query Running Time

Resource pool-specific sub-category filters

To retrieve alerts for a specific resource pool, you can use sub-category filters in combination with the following category filters:

  • thresholds

  • rp_name

If you use these sub-category filters without the RP_NAME filter, the query retrieves alerts for all resource pools in your database.

Sub-Category Filter Alerts Related to Threshold Value Set For:
THRESHOLD_RP_QUERY_MAX_TIME Queries reaching the maximum allowed execution time.
THRESHOLD_RP_QUERY_RESOURCE_REJECT The number of queries with resource rejections.
THRESHOLD_RP_QUERY_QUEUE_TIME The number of queries that ended because of queue time exceeding a limit.
THRESHOLD_RP_QUERY_RUN_TIME The number of queries that ended because of run time exceeding a limit.
THRESHOLD_RP_MEMORY The minimum allowed resource pool size.
THRESHOLD_RP_MAX_MEMORY The maximum allowed resource pool size.

Authentication

Requires an MC-User-Apikey in the request header.

Example request

GET https://<MC_NODE>:5450/webui/api/alerts?category=thresholds&subcategory=<subcategory_filter>

Combine the thresholds category filter with a sub-category filter

This example shows how you can request alerts using cURL with the thresholds category filter and a sub-category filter. You apply the following filters:

  • THRESHOLDS

  • THRESHOLD_NODE_CPU

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?category=thresholds&subcategory=threshold_node_cpu

Response:

[
   {
      "alerts":[
         {
            "id":11749,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 11:04:43.997",
            "updated_time":"2015-11-05 11:04:43.997",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":105,
            "clusterName":"1443122180317_cluster",
            "description":" Database: mydb Lower than threshold Node CPU 10 %   v_mydb_node0002 ;1.03%  v_mydb_node0003 ;0.9%  v_mydb_node0001 ;1.36%  ",
            "summary":"Threshold : Node CPU < 10 %",
            "internal":false,
            "count":1
         },
         {
            "id":11744,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 10:59:46.107",
            "updated_time":"2015-11-05 10:59:46.107",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb2",
            "databaseId":106,
            "clusterName":"1443552354071_cluster",
            "description":" Database: mydb2 Lower than threshold Node CPU 10 %   v_mydb2_node0002 ;0.83%  v_mydb2_node0001 ;1.14%  ",
            "summary":"Threshold : Node CPU < 10 %",
            "internal":false,
            "count":1
         }
      ],
      "total_alerts":2,
      "request_query":"category=thresholds&subcategory=threshold_node_cpu",
      "request_time":"2015-11-05 11:05:28.116"
   }
]

Request an alert on a specific resource pool

This example shows how you can request alerts using cURL on a specific resource pool. The name of the resource pool is resourcepool1. You apply the following filters:

  • THRESHOLDS

  • RP_NAME

  • THRESHOLD_RP_QUERY_RUN_TIME

curl -H "MC-User-ApiKey: ValidUserKey" https://<MC_NODE>:5450/webui/api/alerts?category=thresholds&subcategory=threshold_rp_query_run_time&rp_name=resourcepool1

Response:

[
   {
      "alerts":[
         {
            "id":6525,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 14:25:36.797",
            "updated_time":"2015-11-05 14:25:36.797",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":106,
            "clusterName":"1443552354071_cluster",
            "description":" Resource Pool: resourcepool1  Threshold Name: Ended Query with Run Time Exceeding Limit  Time Interval: 14:20:36 to 14:25:36  Threshold Value: 0 min(s)  Actual Value: 2186 query(s) ",
            "summary":"Resource Pool: resourcepool1; Threshold : Ended Query with Run Time Exceeding Limit > 0 min(s)",
            "internal":false,
            "count":1
         },
         {
            "id":6517,
            "markedRead":false,
            "eventTypeCode":2,
            "create_time":"2015-11-05 14:20:39.541",
            "updated_time":"2015-11-05 14:20:39.541",
            "severity":"warning",
            "status":1,
            "databaseName":"mydb",
            "databaseId":106,
            "clusterName":"1443552354071_cluster",
            "description":" Resource Pool: resourcepool1  Threshold Name: Ended Query with Run Time Exceeding Limit  Time Interval: 14:15:39 to 14:20:39  Threshold Value: 0 min(s)  Actual Value: 2259 query(s) ",
            "summary":"Resource Pool: resourcepool1; Threshold : Ended Query with Run Time Exceeding Limit > 0 min(s)",
            "internal":false,
            "count":1
         }
      ],
      "total_alerts":14,
      "request_query":"category=thresholds&subcategory=threshold_rp_query_run_time&rp_name=resourcepool1",
      "request_time":"2015-11-05 11:07:43.988"
   }
]