IBM Cloud API Docs

Introduction

The IBM Cloud™ Monitoring service helps you gain insight into how your apps are performing and consuming resources. You can use the Monitoring service to expand your collection and retention capabilities when working with metrics in the IBM Cloud, and to be able to define rules and alerts that notify you of conditions that require attention.

The Monitoring service provides the following REST APIs:

  • A Metrics API that you can use to send and retrieve data from a space domain.
  • An Alerts API that you can use to configure alerts on metrics.
  • A Dashboards API that you can use to create, read, update, delete, search, and migrate Grafana 4 dashboards.

For details about using the Monitoring service, see the IBM Cloud docs.

Error handling

The Monitoring service uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

Status code Description Description
200 OK Everything worked as expected.
400 Bad Request The request was unsuccessful, often due to a missing required parameter.
401 Unauthorized The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
500 Server Error Something went wrong.

Methods

Add a new dashboard

POST /v1/metrics/dashboard

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Request Body

Required*
Grafana4DashboardPOST

Dashboard object

Examples:
View

Response

Status Code

  • 200

    New dashboard created

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

  • 412

    Dashboard already exists

No Sample Response

This method does not specify any sample responses.

Update an existing dashboard.

PUT /v1/metrics/dashboard

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Request Body

Required*
Grafana4DashboardPOST

Dashboard object

Examples:
View

Response

Status Code

  • 200

    Dashboard updated

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

  • 412

    Dashboard with a newer version already exists

No Sample Response

This method does not specify any sample responses.

Retrieve a dashboard

GET /v1/metrics/dashboard/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • name
    Required*
    string

    name of dashboard to be deleted

Response

Response Body

Grafana4DashboardGET

Status Code

  • 200

    Dashboard with specified name returned

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

  • 404

    Dashboard not found

Example responses
  • {
  "meta": {
    "expires": "expires",
    "updatedBy": "updatedBy",
    "createdBy": "createdBy",
    "canStar": "canStar",
    "created": "created",
    "canEdit": "canEdit",
    "canSave": "canSave",
    "type": "type",
    "updated": "updated",
    "version": "version",
    "slug": "slug"
  },
  "dashboard": {
    "schemaVersion": 0,
    "timezone": "browser",
    "id": "null",
    "title": "Title",
    "rows": [
      "rows",
      "rows"
    ],
    "version": 6,
    "tags": [
      "tags",
      "tags"
    ]
  }
}

Delete a dashboard

DELETE /v1/metrics/dashboard/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • name
    Required*
    string

    name of the dashboard to be deleted

Response

Status Code

  • 200

    Dashboard deleted

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

  • 404

    Dashboard not found

No Sample Response

This method does not specify any sample responses.

List the available dashboards

GET /v1/metrics/dashboards

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Response

Response Body

DashboardList[]

Status Code

  • 200

    Available dashboard returned

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.

Search the available dashboards

GET /v1/metrics/dashboard/search/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • name
    Required*
    string

    Name of the dashboard

Query Parameters

  • query
    Required*
    string

    name of dashboard being searched

  • tag
    string

    Tag of dashboard being searched

  • starred
    string

    Flag indicating if only starred Dashboards should be returned

Response

Response Body

DashboardList[]

Status Code

  • 200

    Available dashboard returned

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.

Migrate the specified dashboard from Grafana 1.9 to Grafana 4

POST /v1/metrics/dashboard/migrate/{name}

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Path Parameters

  • name
    Required*
    string

    name of the dashboard to be migrated

Query Parameters

  • from
    Required*
    string

    version of Grafana the dashboard is being migrated from. Only "grafana1" is supported for now

  • to
    Required*
    string

    version of Grafana the dashboard is being migrated to. Only "grafana4" is supported for now

  • replace-existing
    boolean

    Flag indicating if the API should replace the existing dashboard, if found. Default is set to "false"

Response

Response Body

DashboardMigrate

Status Code

  • 200

    Migrate result returned

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

  • 404

    A Grafana 1 dashboard with the name specified does not exist

Example responses
  • {
  "response": {
    "version": 6,
    "slug": "slug",
    "status": "status"
  },
  "title": "title",
  "message": "message",
  "status": 0
}

Migrate all dashboards from Grafana 1.9 to Grafana 4

POST /v1/metrics/dashboards/migrate

Request

Custom Headers

  • X-Auth-User-Token
    Required*
    string

    The UAA token or IAM token. The token or apikey must be prefixed with one of the following apikey, iam or uaa, where

    • apikey identifies that the token is an apikey
    • iam identifies that the token specified is an IAM generated token
    • uaa identifies that the token specified is an UAA generated token

    For example: X-Auth-User-Token: apikey SomeIAMGeneratedKey

  • X-Auth-Scope-Id
    string

    The space or org GUID. The GUID must be prefixed with s- to identify a space or o- to identify an organization. This header is required if using UAA token authentication. If using IAM authentication then this header is optional, in which case the account bound to the token will be used as the domain.

Query Parameters

  • from
    Required*
    string

    version of Grafana the dashboard is being migrated from. Only "grafana1" is supported for now

  • to
    Required*
    string

    version of Grafana the dashboard is being migrated to. Only "grafana4" is supported for now

  • replace-existing
    boolean

    Flag indicating if the API should replace the existing dashboard, if found. Default is set to "false"

Response

Response Body

DashboardMigrate[]

Status Code

  • 200

    Migrate results returned

  • 207

    Some errors were encountered in migrating all the dashboards. Check the message sections of the response body

  • 401

    X-Auth-Scope-Id or X-Auth-User-Token invalid or missing

  • 403

    User is forbidden from performing this request

No Sample Response

This method does not specify any sample responses.