SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Dashboard Groups API

Dashboard groups let you collect dashboards with common characteristics in one place in the web UI, so you can view them together or in sequence.
The Dashboard Groups API lets you do the following:

  • Create a new dashboard group: POST /dashboardgroup
  • Retrieve the properties of one or more dashboard groups, using a query encoded on the endpoint URL: GET /dashboardgroup
  • Retrieve the properties of a single dashboard group specified by its ID: GET /dashboardgroup/{id}
  • Update the properties of a single dashboard group specified in the {id} path parameter: PUT /dashboardgroup/{id}
  • Make a deep copy (clone) of the dashboard specified in the request body to the group specified in the {id} path parameter: POST `dashboardgroup/{id}/dashboard
  • Add a mirrored dashboard to a group: PUT /dashboardgroup/{id}
  • Delete the dashboard group specified in the {id} path parameter: DELETE /dashboardgroup/{id}


Dashboard groups have options and functionality that depend on the availability of the mirrored dashboard feature in your organization. Read the Developer Guide topic Working with Dashboards before using the Dashboard Groups API.
If the write permissions feature is available in your organization, you need to ensure you have write permissions for the following dashboard group operations:

  • Adding dashboards to the group, including mirrored dashboards
  • Rearranging the tab order of the group's dashboards in the web UI
  • Renaming or deleting the group
  • Managing links between the group and teams
    To make changes to a dashboard in the group or charts in a group's dashboard, you need write permission for the dashboard.
    To learn more, see the topic Setting Write Permissions in the product documentation.

Retrieve Dashboard Groups Using Query

Retrieves dashboard groups based on search criteria

get /dashboardgroup

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup

Retrieves the properties of one or more dashboard groups, based on search criteria you specify in the endpoint URL. If you don't specify any parameters, you receive the first 50 groups to which the user associated with the auth token has access. Endpoint parameters also control the point in the result set at which the system starts returning groups, and the number of groups to return.

query Parameters
limit
integer <int32>

The maximum number of dashboard groups to return from the overall result set. If the value isn't valid, the system defaults to 50 groups.

name
string

Search string that SignalFx compares to existing dashboard group names. A match occurs if the string matches any part of the name. For example, the query specification name="per" matches the following (ellipses represent other parts of the name):

  • "...dropped per day..."
  • "...95th percentile"
  • "personal disk usage..."
    If you specify `name=""`, the system ignores the search string.
    The string can only contain ASCII characters.
offset
integer <int32>

0-based index of the point in the overall result set where SignalFx starts returning dashboard groups. If the offset value is greater than the size of the query results, you don't receive any results.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful retrieval of dashboard groups.
Note: If SignalFx fails to find any dashboard groups that satisfy the search criteria, you receive HTTP status code 200 with an empty response body.

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Response Schema: application/json
count
integer <int32>

Number of dashboard groups that matched the provided search criteria.
NOTE: This value is the total number of dashboard groups that matched the criteria. Use the results property to determine how many dashboard groups you received in the response body.

results
Array of objects

List of dashboard groups that SignalFx returns, in the form of a JSON array. The number of objects in results depends on the limit and offset parameters:

  • offset specifies point in the overall result set where you want to start receiving results.
  • limit is the number of results you want to receive.
  • offset and limit specify the slice of the overall result set you want to retrieve.
    How many results you receive depends on this slice:
  • If the length of this slice is greater than the number of dashboard groups in the overall result set, then the results array you receive is a slice that starts at offset and ends at count.
  • If the length of the this slice is less than the number of dashboard groups in the overall result set, then the results array you receive a slice of the matching set starting at offset and ending at offset+limit.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": 0,
  • "results":
    [
    ]
}

Create Single Dashboard Group

Creates a dashboard group

post /dashboardgroup

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup

Creates a dashboard group using the properties specified in the request body. If your organization has the write permissions feature enabled, you can use the authorizedWriters property to specify the users and teams who have permission to edit or delete the group or its dashboards.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

Properties that specify a new dashboard group.
If you don't specify dashboards to include in this new group, the system creates a new dashboard and assigns it to this group.

authorizedWriters
object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

dashboardConfigs
Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

name
required
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)

List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Responses

200

Successful creation of the dashboard group

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Response Schema: application/json
authorizedWriters
object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

created
integer <int64> (DashboardgroupCreated)

The dashboard group creation date and time, in the form of a Unix time value, UTC-relative. The system sets this value, and you can't modify it.

creator
string (DashboardgroupCreator)

SignalFx-assigned user ID of the user that created the dashboard group. If the system created this dashboard group, the value is "AAAAAAAAAA". The system sets this value, and you can't modify it.

dashboardConfigs
Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

id
string (DashboardgroupId)

The SignalFx-assigned ID for this dashboard group.

lastUpdated
integer <int64> (DashboardgroupLastUpdated)

The last time the dashboard group was updated, in Unix time UTC-relative. This value is "read-only".

lastUpdatedBy
string (DashboardgroupLastUpdatedBy)

SignalFx-assigned ID of the last user who updated the dashboard group. If the last update was by the system, the value is "AAAAAAAAAA". This value is "read-only".

name
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)

List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "created": 0,
  • "creator": "string",
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "id": "string",
  • "lastUpdated": 0,
  • "lastUpdatedBy": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Delete Single Dashboard Group

Deletes a dashboard group

delete /dashboardgroup/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup/{id}

Deletes the dashboard group specified by the {id} path parameter. Dashboards associated with the group are affected as follows:

  • If the mirrored dashboard feature isn't available in your organization:
    Deleting the dashboard group deletes all the dashboards associated with the group.
  • If the mirrored dashboard feature is available in your organization:
    If dashboards in the group are mirrored in other groups, then deleting the dashboard group doesn't delete the dashboards.
    If dashboards in the group aren't mirrored in other groups, then deleting the dashboard group deletes the dashboards.
path Parameters
id
required
string

The SignalFx-assigned ID of an existing dashboard group.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful deletion

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Retrieve Dashboard Group Using ID

Gets the single dashboard group specified in the {id} path parameter

get /dashboardgroup/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup/{id}

Retrieves a dashboard group specified by the dashboard group ID in the {id} path parameter.

path Parameters
id
required
string

The SignalFx-assigned ID of an existing dashboard group.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful retrieval of the dashboard group specified in the {id} path parameter

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Response Schema: application/json
authorizedWriters
object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

created
integer <int64> (DashboardgroupCreated)

The dashboard group creation date and time, in the form of a Unix time value, UTC-relative. The system sets this value, and you can't modify it.

creator
string (DashboardgroupCreator)

SignalFx-assigned user ID of the user that created the dashboard group. If the system created this dashboard group, the value is "AAAAAAAAAA". The system sets this value, and you can't modify it.

dashboardConfigs
Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

id
string (DashboardgroupId)

The SignalFx-assigned ID for this dashboard group.

lastUpdated
integer <int64> (DashboardgroupLastUpdated)

The last time the dashboard group was updated, in Unix time UTC-relative. This value is "read-only".

lastUpdatedBy
string (DashboardgroupLastUpdatedBy)

SignalFx-assigned ID of the last user who updated the dashboard group. If the last update was by the system, the value is "AAAAAAAAAA". This value is "read-only".

name
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)

List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "created": 0,
  • "creator": "string",
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "id": "string",
  • "lastUpdated": 0,
  • "lastUpdatedBy": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Update Single Dashboard Group

Updates a dashboard group

put /dashboardgroup/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup/{id}

Updates the dashboard group specified by the {id} path parameter, using the properties specified in the request body.
This operation has overwrite semantics. Values you specify in the request body overwrite existing properties. SignalFx either removes or resets properties that you don't specify. Some values you can specify for mirrored dashboard overrides have special meaning:

  • Arrays you specify for to the authorizedWriters, dashboards, dashboardConfigs, and teams array properties overwrite the existing arrays.
  • To add an element to an array, retrieve the existing dashboard group, copy the array, insert into the copy the element you want to add, and send the copy in your PUT request.
  • To add a dashboard mirror, update the dashboardConfigs array with a dashboardConfig that contains an existing dashboard ID.
  • If the write permissions feature is enabled for your organization, the user ID associated with the request's auth token must have write permission for the group.
path Parameters
id
required
string

SignalFx-assigned ID of the dashboard group you want to update

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

Properties of an existing dashboard group, in the form of a JSON object

authorizedWriters
object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

dashboardConfigs
Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

name
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)

List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Responses

200

Successful update of the dashboard group

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Response Schema: application/json
authorizedWriters
object (Organizations and teams with write permission for an object)

Set of organizations and teams that have write permission for the dashboard group, in the form of a JSON object. If your organization has the write permissions feature enabled, you can use this object to specify the user and team IDs that have write access to the dashboard group

created
integer <int64> (DashboardgroupCreated)

The dashboard group creation date and time, in the form of a Unix time value, UTC-relative. The system sets this value, and you can't modify it.

creator
string (DashboardgroupCreator)

SignalFx-assigned user ID of the user that created the dashboard group. If the system created this dashboard group, the value is "AAAAAAAAAA". The system sets this value, and you can't modify it.

dashboardConfigs
Array of objects (List of dashboard configurations)

List of dashboard configurations associated with the dashboard group, in the form of a JSON array of JSON objects. In the web UI, SignalFx uses the set of configurations for a group to determine which dashboards to display for the group.

dashboards
Array of strings (List of dashboards to add to the dashboard group)

List of dashboards, in the form of a JSON array of dashboard IDs. The system adds the specified dashboards to the dashboard group you're creating. If you omit the property, the system creates a new dashboard and assigns it to the new dashboard group.

description
string <UTF-8> (DashboardgroupDescription) <= 1024 characters

Description of the dashboard group. This value appears in the tooltip for the dashboard group on the Dashboards page in the web UI. For this value, you can use up to 1024 UTF-8 characters.

id
string (DashboardgroupId)

The SignalFx-assigned ID for this dashboard group.

lastUpdated
integer <int64> (DashboardgroupLastUpdated)

The last time the dashboard group was updated, in Unix time UTC-relative. This value is "read-only".

lastUpdatedBy
string (DashboardgroupLastUpdatedBy)

SignalFx-assigned ID of the last user who updated the dashboard group. If the last update was by the system, the value is "AAAAAAAAAA". This value is "read-only".

name
string (DashboardgroupName) non-empty

Name of the dashboard group. This value identifies the dashboard group in the web UI. It appears on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever you're viewing a dashboard that the group contains.

teams
Array of strings (DashboardgroupTeams)

List of existing teams, in the form of a JSON array of team IDs. The dashboard group appears on the team landing page for any team in the list.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "created": 0,
  • "creator": "string",
  • "dashboardConfigs":
    [
    ],
  • "dashboards":
    [
    ],
  • "description": "string",
  • "id": "string",
  • "lastUpdated": 0,
  • "lastUpdatedBy": "string",
  • "name": "string",
  • "teams":
    [
    ]
}

Clone Dashboard

Make a clone of an existing dashboard

post /dashboardgroup/{id}/dashboard

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{realm}.signalfx.com/v2/dashboardgroup/{id}/dashboard

NOTE: This operation doesn't create a mirrored dashboard. Use PUT dashboardgroup/{id} to add a mirrored dashboard to a group.
Creates a new v2 dashboard from an existing dashboard and associates it with the dashboard group specified by the {id} path parameter. The new dashboard is an exact copy of the existing dashboard, but you can change its name, description, and filters by specifying them in your request.
If the write permissions feature is available in your organization, you need to have write permission for the dashboard group into which you're cloning the dashboard.
If you don't have write permissions for the dashboard you're cloning, SignalFx sets the dashboard permissions on the cloned dashboard so that any user can edit it.

path Parameters
id
required
string

The SignalFx-assigned ID of an existing dashboard group.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is application/json.

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

Contains properties that SignalFx uses to clone the dashboard into the dashboard group specified in the {id} path parameter. The only required property is sourceDashboard, which specifies the dashboard to copy.

description
string (DashboardDescription)

Description of a cloned dashboard

filters
object (Filters to apply to all the charts of the cloned dashboard)

Specifies the properties of filters to apply to the cloned dashboard.
This is an optional property that you only need to use if you want to override the filters property of the dashboard you're cloning. Filters give you fine-grained control over the data displayed in the charts in the dashboard. You can specify ad hoc filters or save them as variables for repeated use of the filter criteria.
You can also use filters to apply a custom time window to all of the charts in the dashboard.

name
string (DashboardName)

A human-readable label for the dashboard. The web UI displays this label in the dashboard's group.

sourceDashboard
required
string (Dashboard ID of a cloned dashboard)

The ID of the dashboard to clone into the dashboard group whose ID is specified in the {id} path parameter

Responses

200

Successful clone of a dashboard

Response Headers
Content-Type
string
Default: "application/json; charset=utf8"

Format of the response payload.

Response Schema: application/json
id
string

SignalFx-assigned ID of the new dashboard.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "filters":
    {
    },
  • "name": "string",
  • "sourceDashboard": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string"
}

© Copyright 2019 SignalFx.

Third-party license information