SignalFx

Suggest Edits

/session

Creates a new session token

 
posthttps://api.signalfx.com/v2/session
curl -i \
   -H "Content-Type: application/json" \
   -X POST \
   -d \
   '{
     "email": "user@organization.com",
     "password": "userpassword"
   }' \
   https://api.signalfx.com/v2/session
A binary file was returned

You couldn't be authenticated

{
 'accessToken': '<access-token>',
 'createdBy': 'CkClZUKAIAQ',
 'createdMs': 1465239513540,
 'disabled': false,
 'email': 'user@organization.com',
 'expiryMs': 1467831513540,
 'id': 'CkSfGddAAAg',
 'organizationId': 'CMtLSYXAEJQ',
 'sessionType': 'ORG_USER',
 'updatedBy': null,
 'updatedMs': 1465239513540,
 'userId': 'CkClZUKAIAQ',
 'userName': null
}
{
    "type": "error",
    "status": 401,
    "message": "The email/password combination was entered incorrectly. Please try again."
}

Body Params

email

The email address of the user

password

The password for the user

 
Suggest Edits

/session

Invalidates an existing session token

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/session
curl -i \
   -H "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
   -H "Content-Type: application/json" \
   -X DELETE \
   https://api.signalfx.com/v2/session
A binary file was returned

You couldn't be authenticated

{
    "type": "error",
    "status": 401,
    "message": "The email/password combination was entered incorrectly. Please try again."
}

Body Params

X-SF-Token

The session's access token

 
Suggest Edits

/datapoint

Send metric data points to SignalFx

 
posthttps://ingest.signalfx.com/v2/datapoint
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview

curl -i \
  --header  "Content-Type: application/json" \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  -X POST \
  -d \
  '{ 
  	"gauge": [{ 
    	"metric": "test.gauge",
      "value": 42,
      "dimensions": { "host": "testserver" } 
    },
    { 
    	"metric": "test.gauge.with_timestamp",
      "value": 42,
      "timestamp": 1485801354682,
      "dimensions": { "host": "testserver" } 
    }],
    "counter": [{ 
    	"metric": "test.counter",
      "value": 1,
      "dimensions": { "host": "testserver" }
    }],
    "cumulative_counter": [{ 
    	"metric": "test.cumulative_counter",
      "value": 100,
      "dimensions": { "host": "testserver" }
    }]  
  }' \
  https://ingest.signalfx.com/v2/datapoint
A binary file was returned

You couldn't be authenticated

"OK"
<string error message>
"Unauthorized"

Body Params

gauge

Array of gauge metric datapoint objects

counter

Array of counter metric datapoint objects

cumulative_counter

Array of cumulative counter metric datapoint objects

 

Datapoint object model

The datapoint is map of key value pairs, some required, some optional:

  • metric (required) - a string conforming to the rules below

  • value (required) - a number, either floating point or integer

  • dimensions (optional) - a map of key value pairs conforming to the rules below

  • timestamp (optional) - the timestamp of the datapoint in milliseconds since epoch. The default is the time the datapoint is received by SignalFx.

Criteria for Metric and Dimension Names and Values

The following criteria describe acceptable metric and dimension information that can be sent in a datapoint.

  • Metric (the metric name) can be any non-empty UTF-8 string, with a maximum length <= 256 characters

  • Value (the metric value) can be any integer or float value ±1.79769313486231570E+308

  • Dimension name:

    • has a maximum length of 128 characters

    • may not start with _ or sf_

    • must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression:

      ^[a-zA-Z][a-zA-Z0-9_-]*$

  • Dimension value can be any non-empty UTF-8 string, with a maximum length <= 256 characters

SignalFx will reject any datapoint request that doesn't meet the above criteria.

Note

The criteria for dimension names and values shown above also apply to custom properties that are not sent as part of a datapoint, but that may be set later. In addition, custom property names should not start with aws_.

Suggest Edits

/backfill

 

Header Auth

 Authentication is required for this endpoint.
posthttps://backfill.signalfx.com/v1/backfill
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview
# The following example shows how to send a backfill 4 datapoints for a counter type starting midnight, December 20th 2015 with values 100, 200, 400, 300:

$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"timestamp":1450569600000, "value":100}
          {"timestamp":1450569610000, "value":200}
          {"timestamp":1450569620000, "value":400}
          {"timestamp":1450569630000, "value":300}' \
  "https://backfill.signalfx.com/v1/backfill?orgid=MY_ORG_ID&sfxdim_mydimension=myvalue&metric=MY_METRIC_NAME&metric_type=counter"
A binary file was returned

You couldn't be authenticated

Body Params

orgid

your organization ID.

metric

the name of the metric being backfilled.

sfxdim_DIMENSION_NAME

replace DIMENSION_NAME with your dimension. The value should be the value of the dimension. Add one such parameter per dimension.

metric_type

type of your metric. Can be gauge, counter or cumulative_counter.

 

All the examples in this document are shown using the httpie command-line utility, which provides very convenient interactions with JSON-based HTTP REST APIs.

If you need to send historical data, SignalFx provides a backfill API endpoint that allows for datapoints to be ingested into the system in the past. This is in contrast to the the /datapoint endpoint, which is designed to accept datapoints in a streaming manner, as they are generated, and expects the timestamps of the datapoints to be in monotonically increasing order (when they are specified)

This ability comes with certain requirements/best practices that the user must keep in mind to ensure the desired results are obtained.

  • A given backfill call may only target a single metric time series, addressed by its dimensions, its metric type and its metric name.

  • Within a given backfill call, datapoints must be sent in chronological order (for the same reasons the /datapoint endpoint only accepts datapoints in order).

  • A single backfill call must contain exact multiples of one hour of datapoints starting from the top of an hour (e.g. 7:00 AM to 8:00AM, 9:00PM to 3:00AM). It is recommended that each call contains a few thousand datapoints (e.g. 1 day or 1-min resolution points, or 1 hour of 1-sec resolution points).

  • Backfill calls should not contain significant gaps in the history of data being backfilled because they overwrite all existing data for the period being backfilled. If there is a need to backfill multiple disjoint periods of time, they should be backfilled through distinct API calls.

  • Backfill will overwrite any existing TSDB data. Derived metrics and the output of analytics in charts based on historical data that is being overwritten by a backfill call will not be recalculated with the new data.

The /backfill API endpoint supports the same ingest styles as the /datapoint endpoint with regard to content type (JSON and ProtocolBuffers) and the ability to stream multiple datapoints through the same HTTP POST request. Refer to the examples in Metric Data Overview for the corresponding documentation.

Specify metric, dimensions and metric type as query parameters.

  • For the metric, the query parameter is "metric".

  • For any dimension XYZ, the query parameter is sfxdim_XYZ. For example, to backfill for the dimension "host", one would use the query parameter sfxdim_host.

  • For metric type, the query parameter is metric_type. Just as for regular ingest, the available metric types are gauge, counter and cumulative_counter. The metric type for a particular metric should not be changed across different calls to the backfill API. If the metric is already in our system we will use the metric type of the existing metric. If it is not present we will create the metric with the metric type you specify. If the metric_type query parameter is absent then it is assumed to be a gauge.

Each datapoint should each be represented as a JSON Object within braces '{ .. }'. Successive values should be separated by a space (NOT by a comma). Make sure both the timestamp and the value are sent as numbers (NOT as strings).

Note: orgid can be looked up from the /organization endpoint.

Suggest Edits

/event

Send custom event to SignalFx

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
posthttps://ingest.signalfx.com/v2/event
# the api takes an array of event objects
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview
curl -i \
  --header "Content-Type: application/json" \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  -X POST \
  -d \
  '[{
    "category": "USER_DEFINED",
    "eventType": "test event",
    "dimensions": { "environment": "production", "service": "API" },
    "properties": { "sha1": "1234567890abc" },
    "timestamp": 1480870800000
  }]' \
  https://ingest.signalfx.com/v2/event
A binary file was returned

You couldn't be authenticated

 

Custom events can be sent to SignalFx, and are commonly used to make a note of when code or infrastructure deployments happen, so that changes to key metrics can be correlated with the deployments.

For background information on how events are available to be viewed in the SignalFx web UI, see the documentation.

Object Model

This API takes an array of event objects of the form:

  • eventType: (required) The name used to define the "type" of the event and conforms to the rules below. For example: "code push", "database start". You will use this type to find your events.

  • dimensions: (optional) A map of name value pairs conforming to the rules below which will be used to distinguish different "types" of events. For example, environment information or database names. Dimension values should not change for each event you send.

  • properties: (optional) A map of name value pairs conforming to the rules below that are unique to the event that occurred. For example, SHA1 of the code commit pushed or who started the database.

  • category: (optional) The category of event. Defaults to USER_DEFINED but other allowable fields include ALERT, AUDIT, JOB, COLLECTD, SERVICE_DISCOVERY, and EXCEPTION.

  • timestamp:(optional) The timestamp of the event in milliseconds since epoch, defaulting to the time the event was received by SignalFx.

If you want to send a single event, it would be an array with one element.

To see the events you have sent, click the Events button in the top right corner of any dashboard and a list of recently submitted events will appear on a pullout from the right. You can also type the "eventType" value of the event into a chart builder's signal entry field in order to overlay it on top of existing data.

Criteria for names and values passed to this API

The following criteria describe acceptable information that can be sent with an event.

  • eventType (the kind of event) can be any non-empty UTF-8 string, with a maximum length <= 256 characters

  • Dimension or property name:

    • has a maximum length of 128 characters

    • may not start with _ or sf_ (In addition, a property name should not start with aws_)

    • must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression:

      ^[a-zA-Z][a-zA-Z0-9_-]*$

  • Dimension or property values can be any non-empty UTF-8 string, with a maximum length <= 256 characters

Suggest Edits

/timeserieswindow

Retrieve datapoints from time series for a given time window

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v1/timeserieswindow
$ curl \
   --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
   --header "Content-Type: application/json" \
   --request GET \
   'https://api.signalfx.com/v1/timeserieswindow?query=sf_metric:"test.gauge"&startMs=1447228800000&endMs=1447373079476&resolution=1000'
A binary file was returned

You couldn't be authenticated

{
    "data": {
        "CTpQ1J_AYAs": [
            [
                1447367652000,
                1
            ]
        ]
    },
    "errors": []
}

Query Params

query
string

Elasticsearch string query that specifies metric time series to retrieve. (Refer to our search syntax)

startMs
int32

Starting point of time window within which to find datapoints, in milliseconds since Unix epoch

endMs
int32

End point of time window within which to find datapoints, in milliseconds since Unix epoch

resolution
int32

The data resolution, in milliseconds, in which to return the data points. Acceptable values are 1000 (1s), 60000 (1m), 300000 (5m), and 3600000 (1h).

 
Suggest Edits

/event

Retrieve events from SignalFx

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v1/event
curl -i \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  -X GET \
  https://api.signalfx.com/v1/event?query=*
 
# Return events in timestamp order
# Note that orderBy is "sf_timestamp" but return response is "timestamp"

curl -i \
   --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  -X GET \
  https://api.signalfx.com/v1/event?query=* \
  &orderBy=sf_timestamp
A binary file was returned

You couldn't be authenticated

 [{
  "id" : "EVENT_ID",
  "tsId" : "TIMESERIES_ID",
  "timestamp" : "USER_PROVIDED_TIMESTAMP_OR_EVENT_FIRED_TIMESTAMP",
  // all values in properties will be a string except for the following keys
  // "sources", "inputSources", "inputValues", and "inputs". Which will be
  // maps on objects with a sf_eventCategory of "ALERT"
  "properties" : "KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES",
  "metadata" : "KEY_VALUE_MAP_OF_EVENT_METADATA",
  "eventCreatedOnMs" : "WALLCLOCK_TIME_EVENT_WAS_CREATED"
},
//….more events….
]

// Example:

 [ {
  "id" : "Cxi8E57AIAA",
  "tsId" : "Cvkdh1NAAAA",
  "timestamp" : 1479473687302,
  "properties" : {
    "foo" : "bar"
  },
  "metadata" : {
    "sf_eventCategory" : "USER_DEFINED",
    "sf_eventType" : "test event"
  },
  "eventCreatedOnMs" : 1479473687606
},
//….more events….
]

// The response can be more complex depending on the event category, 
// for example, response for ALERT event

[ {
  "id" : "Cxi0Iu7AIAA",
  "tsId" : "CwSX6WXAAAA",
  "timestamp" : 1479471565000,
  "properties" : {
    "inputs" : {
      "high" : {
        "value" : 4.0
      },
      "in" : {
        "key" : {
          "sf_metric" : "jvm.cpu.load",
          "sf_source" : "myhost"
        },
        "value" : 3.607242375
      }
    },
    "was" : "too high",
    "is" : "ok",
    "sf_resolutionMs" : 1000,
    "sf_schema" : 3,
    "incidentId" : "CxizWsMAEAA"
  },
  "metadata" : {
    "sf_eventCategory" : "ALERT",
    "sf_eventType" : "test event"
  },
  "eventCreatedOnMs" : 1479471566534
},
//... more events ...
]

Query Params

query
string

Elasticsearch query that specifies events to retrieve (refer to our search syntax)

from
int32

Minimum event timestamp in milliseconds; relative to now if <= 0

to
int32

Maximum event timestamp in milliseconds; relative to now if <= 0

orderBy
string

Ordering to apply

offset
int32

Page offset from beginning of result set. 0 is the beginning of set.

limit
int32

Maximum page size or -1 to fetch 1000 entries. Number of fetched results may be less.

 
Suggest Edits

/metric

Search metrics

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metric?query=service:jetty

{
  "results" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "service" : "jetty"
    },
    "tags" : [ "test-tag" ],
    "type": "GAUGE",
    "name" : "jvm.cpu.load",
    "description" : "CPU load guage"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "tags" : LIST_OF_TAG_STRINGS,
    "type" : TYPE_OF_METRIC,
    "name" : NAME_OF_METRIC,
    "description" : DESCRIPTION_OF_METRIC
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Query Params

query
string

An elasticsearch string query (refer to our search syntax)

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/metric/:name

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric/name
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metric/jvm.cpu.load

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "service" : "jetty"
  },
  "tags" : [ "test-tag" ],
  "type": "GAUGE",
  "name" : "jvm.cpu.load",
  "description" : "CPU load guage"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "type" : TYPE_OF_METRIC,
  "name" : NAME_OF_METRIC,
  "description" : DESCRIPTION_OF_METRIC
}

Path Params

name
string
required

Name of metric

 
Suggest Edits

/metric/:name

Create or update a metric object

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/metric/metric/name
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "name" : "request_count", "description": "Number of requests", "type": "COUNTER", "tags": ["test-tag"], "customProperties": { "tier" : "web" } }' \
  https://api.signalfx.com/v2/metric/request_count
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "tier" : "web"
  },
  "tags" : [ "test-tag" ],
  "type" : "COUNTER",
  "description": "Number of requests",
  "name" : "request_count"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "description": DESCRIPTION,
  "type" : TYPE_OF_METRIC,
  "name" : NAME_OF_METRIC
}

Path Params

name
string
required

(Required) Name of metric. Refer to metric name criteria.

Body Params

type

(Required) The type of metric, one of: GAUGE, COUNTER, or CUMULATIVE_COUNTER

description

(Optional) A description for the metric

customProperties

(Optional) Properties to associate with this metric. Criteria for property names and values are the same as those listed for dimensions here.

tags

(Optional) Tags to associate with this metric

 
Suggest Edits

/dimension

Search dimensions

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric/dimension?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/dimension?query=region:japan

{
  "results" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "region" : "japan"
    },
    "tags" : [ "test-tag" ],
    "key" : "host",
    "value" : "lb-tokyo",
    "description" : "A loadbalancer in Tokyo"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "tags" : LIST_OF_TAG_STRINGS,
    "key" : KEY_OF_DIMENSION,
    "value" : VALUE_OF_DIMENSION,
    "description" : DESCRIPTION
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/dimension/:key/:value

Get a dimension object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/dimension/key/value
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/dimension/host/lb-tokyo

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "region" : "japan"
  },
  "tags" : [ "test-tag" ],
  "key" : "host",
  "value" : "lb-tokyo",
  "description" : "A loadbalancer in Tokyo"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "key" : KEY_OF_DIMENSION,
  "value" : VALUE_OF_DIMENSION,
  "description" : DESCRIPTION
}

Path Params

key
string
required

Dimension key

value
string
required

Dimension value

 
Suggest Edits

/dimension/:key/:value

Update (overwrite) metadata for a dimension

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dimension/key/value
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "key" : "host", "value": "lb-tokyo", "tags": ["test-tag"], "customProperties": { "region" : "japan" } }' \
  https://api.signalfx.com/v2/dimension/host/lb-tokyo
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "region" : "japan"
  },
  "tags" : [ "test-tag" ],
  "key" : "host",
  "value" : "lb-tokyo",
  "description" : null
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "key" : KEY_OF_DIMENSION,
  "value" : VALUE_OF_DIMENSION,
  "description" : DESCRIPTION
}

Path Params

key
string
required

(Required) Key for the dimension.

value
string
required

(Required) Value for the dimension.

Body Params

description

(Optional) A description for the dimension

customProperties

(Optional) Properties to associate with this dimension value

tags

(Optional) Tags to associate with this dimension value

 
Suggest Edits

/metrictimeseries

Search metric time series

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric/metrictimeseries?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metrictimeseries?query=region:japan

{
  "results" : [ {
    "id" : "ABCDEFABCDE",
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "region" : "japan"
    },
    "dimensions" : {
      "host" : "lb-tokyo"
    },
    "tags" : [ "test-tag" ],
    "metric" : "request_count",
    "metricType" : "COUNTER"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "dimensions" : KEY_VALUE_MAP_OF_DIMENSIONS,
    "tags" : LIST_OF_TAG_STRINGS,
    "metric" : NAME_OF_METRIC,
    "metricType" : TYPE_OF_METRIC
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/metrictimeseries/:id

Get a metric time series object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metrictimeseries/id
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metrictimeseries/ABCDEFABCDE

{
  "id" : "ABCDEFABCDE",
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "region" : "japan"
  },
  "dimensions" : {
    "host" : "lb-tokyo"
  },
  "tags" : [ "test-tag" ],
  "metric" : "request_count",
  "metricType" : "COUNTER"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "dimensions" : KEY_VALUE_MAP_OF_DIMENSIONS,
  "tags" : LIST_OF_TAG_STRINGS,
  "metric" : NAME_OF_METRIC,
  "metricType" : TYPE_OF_METRIC
}

Path Params

id
string
required

ID of a metric time series

 
Suggest Edits

/tag

Search tags

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric/tag?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag?query=*

{
  "results" : [ {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1450134495381,
    "lastUpdated" : 1450134495386,
    "customProperties" : { },
    "name" : "test-tag",
    "description" : "test description"
  }, {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1449855986386,
    "lastUpdated" : 1449855986393,
    "customProperties" : { },
    "name" : "test-tag-2",
    "description" : ""
  }, {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1450128386054,
    "lastUpdated" : 1450128386060,
    "customProperties" : { },
    "name" : "test-tag-3",
    "description": ""
  } ],
  "count" : 3
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "name" : NAME_OF_TAG,
    "description" : DESCRIPTION_OF_TAG
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/tag/:name

Get a tag object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/tag/name
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag/test-tag

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {},
  "name" : "test-tag",
  "description": "test description"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG,
  "description" : DESCRIPTION_OF_TAG
}

Path Params

name
string
required

Name of the tag to get

 
Suggest Edits

/tag/:name

Create or update tag properties

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/tag/name
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "description": "my test tag", "customProperties": { "tier" : "web" } }' \
  https://api.signalfx.com/v2/tag/test-tag
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "tier" : "web"
  },
  "name" : "test-tag",
  "description" : "my test tag"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG,
  "description" : DESCRIPTION
}

Path Params

name
string
required

Name of the tag to create or update

Body Params

description

(Optional) Description for tags

customProperties

(Optional) Custom properties to associate with the tag and all objects associated with this tag

 
Suggest Edits

/tag/:name

Delete a tag

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/tag/name
$ curl --request DELETE --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag/test-tag

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {},
  "name" : "test-tag"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG
}
"Unable to find the given tag."

Path Params

name
string
required

Name of the tag to delete

 
Suggest Edits

Detector Model

 

A detector is a collection of rules that define who should be notified when certain detect functions within SignalFlow fire alerts. Each rule maps a detect label to a severity and a list of notifications. When the conditions within the given detect function are fulfilled, notifications will be sent to the destinations defined in the rule for that detect function.

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Detector Model

Property
Type
Description

id

String

ID of the detector

name

String

Name of the detector

description

String

Description for the detector

rules

List of Rules

Rules that bind detect blocks in the program text to notification destinations

programText

String

Signalflow program text for the detector

maxDelay

Long

Used to handle late datapoints. Upper limit is 15 minutes( 900000) see help documentation for details

visualizationOptions

VisualizationOptions

Visualization options to use when viewing the detector in the SignalFx web UI

tags

List of Strings

Tags associated with the detector

teams

List of Team IDs

Team IDs to associate the detector to.

Rule Model

Property
Type
Description

detectLabel

String

A detectLabel which matches a detect label within the program text.

description

String

(optional) Human-readable description for this rule.

severity

SeverityType

The severity of the rule, must be one of: Critical, Warning, Major, Minor, Info.

disabled

boolean

(false by default) When true, notifications and events will not be generated for the detect label.

notifications

Array of Notifications

See the Notifications models below. Determines where notifications will be sent when an incident occurs.

parameterizedBody

String

Custom notification message body for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". For an example message, see Detector update. To use the variables available, surround the variables with double brackets {{ variable }}. Triple brackets can be used to indicate that this variable value will not get escaped. For a full list of available variables, go to the documentation.

parameterizedSubject

String

Custom notification message subject for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". For an example message, see Detector update. To use the variables available, surround the variables with double brackets {{ variable }}. Triple brackets can be used to indicate that this variable value will not get escaped. For a full list of available variables, go to the documentation.

runbookUrl

String

URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the parameterizedBody or parameterizedSubject field.

tip

String

Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the parameterizedBody or parameterizedSubject field.

Notifications Models

Email

Property
Type
Description

type

String

Must be "Email"

email

String

The email address to send the notification to

PagerDuty

Property
Type
Description

type

String

Must be "PagerDuty"

credentialId

String

ID of a PagerDuty credential

Slack

Property
Type
Description

type

String

Must be "Slack"

credentialId

String

ID of a Slack credential

channel

String

A Slack channel name

HipChat

Property
Type
Description

type

String

Must be "HipChat"

credentialId

String

ID of a HipChat credential

room

String

A HipChat room name

ServiceNow

Property
Type
Description

type

String

Must be "ServiceNow"

credentialId

String

ID of a ServiceNow credential

VictorOps

Property
Type
Description

type

String

Must be "VictorOps"

credentialId

String

ID of a VictorOps credential

routingKey

String

A VictorOps routing key

Webhook

Property
Type
Description

type

String

Must be "Webhook"

url

String

The URL to call

secret

String

(Optional) When provided, the HTTP request will contain a X-SFX-Signature header containing the Base64 encoded HMAC-SHA1 digest of the request body using the shared secret.

Team

Property
Type
Description

type

String

Must be "Team"

team

String

ID of a team

TeamEmail

Property
Type
Description

type

String

Must be "TeamEmail"

team

String

ID of a team

VisualizationOptions Model

Property
Type
Description

time

TimeConfig

Controls the time span visualized.

showDataMarkers

boolean

(false by default) When true, markers will be drawn for each datapoint within the visualization.

TimeConfig

Property
Type
Description

type

string

Must be "relative" or "absolute". The type of time span defined.

range

long

(relative only) The time range prior to now to visualize, in milliseconds. For example, 60000 would visualize the last 60 seconds.

start

long

(absolute only) Milliseconds since epoch.

end

long

(absolute only) Milliseconds since epoch.

Suggest Edits

/detector

Return information for all or specified detectors

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector?tags=mytag
A binary file was returned

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "id": "...",
    "name": "My detector",
    "tags": ["mytag"],
    ...
  }]
}

Query Params

name
string

A name or part of a name for detectors to search for

tags
string

Tag names that detectors must have to be returned (use multiple query parameters to filter by multiple tags). All given tags must be present on a detector for it to be returned.

offset
int32

Offset of results to return

limit
int32

Number of results to return

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector

Create a detector

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/detector
# Consider using detector/validate before posting your detector
# See https://developers.signalfx.com/v2/docs/detectorvalidate
$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector << EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

{
    "created": 1470704945599,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": null,
    "id": "ABCDEFGHIJ",
    "lastUpdated": 1470705776335,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "maxDelay": null,
    "name": "CPU load too high",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "severity": "Critical"
        }
    ],
    "tags": [],
    "visualizationOptions": null
}

Body Params

name

The name of the detector

programText

SignalFlow program text for the detector

rules

See Rule model

description

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions

(optional) See VisualizationOptions model

tags

(optional) List of tags to associate with the detector

 
Suggest Edits

/detector/:id

Get a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEF123456
{
    "created": 1470704945599,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": null,
    "id": "ABCDEF123456",
    "lastUpdated": 1470705776335,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "maxDelay": null,
    "name": "CPU load too high",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "severity": "Critical"
        }
    ],
    "tags": [],
    "visualizationOptions": null
}
A binary file was returned

You couldn't be authenticated

{
    "created": CREATED_ON_TIMESTAMP,
    "creator": CREATOR_ID,
    "customProperties": CUSTOM_PROPERTIES_MAP,
    "description": DESCRIPTION_TEXT,
    "id": DETECTOR_ID,
    "lastUpdated": LAST_UPDATED_ON_TIMESTAMP,
    "lastUpdatedBy": LAST_UPDATED_BY_ID,
    "maxDelay": MAX_DELAY_VALUE,
    "name": NAME_OF_DETECTOR,
    "programText": SIGNALFLOW_PROGRAM,
    "rules": [
        {
            "description": RULE_DESCRIPTION,
            "detectLabel": SIGNALFLOW_DETECT_LABEL,
            "enabled": RULE_ENABLED_STATE,
            "notifications": RULE_NOTIFICATIONS,
            "severity": RULE_SEVERITY
        }
    ],
    "tags": DETECTOR_TAGS,
    "visualizationOptions": VISUALIZATION_OPTIONS
}

Path Params

id
string
required

(Required) ID of detector

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id

Update a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id
# Consider using detector/validate before updating your detector
# See https://developers.signalfx.com/v2/docs/detectorvalidate
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ <<EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
    "parameterizedSubject": "{{ruleSeverity}} Alert: {{{ruleName}}} {{{detectorName}}}",
    "parameterizedBody": "{{#if anomalous}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" triggered\n{{else}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" cleared{{/if}}\n\n{{#if anomalous}}\nTriggering condition: {{{readableRule}}}\n{{/if}}\n\n{{#if anomalous}}Signal value: {{inputs.A.value}}\n{{else}}Current signal value: {{inputs.A.value}}\n{{/if}}\n\n{{#notEmpty dimensions}}\nSignal details:\n{{{dimensions}}}\n{{/notEmpty}}\n\n{{#if anomalous}}{{#if runbookUrl}}Runbook: {{{runbookUrl}}}{{/if}}\n\n{{#if tip}}Tip: {{{tip}}}{{/if}}\n{{/if}}"
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

{
    "created": 1507735007857,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": "",
    "id": "ABCDEFGHIJ",
    "labelResolutions": {
        "Load above 50%": 1000
    },
    "lastUpdated": 1507735366261,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "locked": false,
    "maxDelay": null,
    "name": "CPU load too high",
    "overMTSLimit": false,
    "packageSpecifications": "",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "parameterizedBody": "{{#if anomalous}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" triggered\n{{else}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" cleared{{/if}}\n\n{{#if anomalous}}\nTriggering condition: {{{readableRule}}}\n{{/if}}\n\n{{#if anomalous}}Signal value: {{inputs.A.value}}\n{{else}}Current signal value: {{inputs.A.value}}\n{{/if}}\n\n{{#notEmpty dimensions}}\nSignal details:\n{{{dimensions}}}\n{{/notEmpty}}\n\n{{#if anomalous}}{{#if runbookUrl}}Runbook: {{{runbookUrl}}}{{/if}}\n\n{{#if tip}}Tip: {{{tip}}}{{/if}}\n{{/if}}",
            "parameterizedSubject": "{{ruleSeverity}} Alert: {{{ruleName}}} {{{detectorName}}}",
            "severity": "Critical"
        }
    ],
    "tags": [],
    "teams": [],
    "visualizationOptions": null
}

Path Params

id
string
required

Body Params

name

The name of the detector

programText

Signalflow program text for the detector

rules

See Rule model

description

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions

(optional) See VisualizationOptions model

tags

(optional) List of tags to associate with the detector

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id

Delete a detector and clear all of its active alerts

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/detector/id
$ curl \
  --request DELETE \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEF123456
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

(Required) ID of detector

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id/enable

Enable all or part of a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id/enable
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '["my detect label"]' \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/enable
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Body Params

body

List of detect labels to enable. If no list is provided, all detect functions will be enabled.

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id/disable

Disable all or part of a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id/disable
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '["my detect label"]' \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/disable
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Body Params

body

List of detect labels to disable. If no list is provided, all detect functions will be disabled.

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id/events

Get events generated by a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id/events
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/events
A binary file was returned

You couldn't be authenticated

{
  ...
}

Path Params

id
string
required

Query Params

from
int64

Starting point of the time range for which events will be selected, in milliseconds from epoch

to
int64

End point of the time range for which events will be selected, in milliseconds from epoch

limit
int32

Number of results to return

offset
int32

Offset of results to return

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id/incidents

Show active incidents for a detector.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id/incidents
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/incidents
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Query Params

limit
int64

Number of results to return

offset
int64

Offset of results to return

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/validate

Validating a detector before posting it is recommended.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/detector/validate
$ curl \
  --request POST \
  --header "X-SF-Token: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector/validate << EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

name

The name of the detector

programText

SignalFlow program text for the detector

rules

See Rule model

description

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions

(optional) See VisualizationOptions model

tags

(optional) List of tags to associate with the detector

 
Suggest Edits

Incident Model

 

An incident is a collection of related events generated by a detector. Each incident has a triggering (or "alerting") event, when an alert notification is sent to the notification recipients, and a clearing (or "resolving") event, when an "ok" notification is sent.

Some incident APIs support only v2 detectors

Some incident APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API. See individual APIs for specifics.

Incident Model

Property
Type
Description

incidentId

String

ID of incident

detectorId

String

ID of detector

detectLabel

String

Label for originating detect function in detector

active

boolean

True when the incident hasn't been resolved yet

severity

String

Detector rule severity, one of: Critical, Warning, Major, Minor, Info

anomalyState

String

Current anomaly state, one of: TOO_HIGH, OK, TOO_LOW, ANOMALOUS, INCONCLUSIVE, STOPPED, CLEARED

events

List of IncidentEvents

Events associated with the incident

duration

long

For resolved incidents, milliseconds elapsed between the triggering event and the resolving event. Only present if the incident has already been resolved.

IncidentEvent Model

Property
Type
Description

id

String

ID of event

timestamp

long

The timestamp for the event

detectorId

String

ID of originating detector for the event

detectLabel

String

Label for the originating detect function for event

severity

String

Rule Severity for the originating detect label. One of: Critical, Warning, Major, Minor, Info.

incidentId

String

ID of incident the event is a part of

anomalyState

String

Anomaly state for event, one of: TOO_LOW, OK, TOO_HIGH, ANOMALOUS, INCONCLUSIVE, STOPPED, CLEARED

inputs

List of IncidentEventSources

Inputs involved in the event

IncidentEventSource Model

Property
Type
Description

dimensions

String to String Map

Dimension key/value pairs identifying the source

value

Number

The value of the source at the time of the event

fragment

String

SignalFlow program fragment the source is computed from

Suggest Edits

/incident

Return information for incidents

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/incident
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident
A binary file was returned

You couldn't be authenticated

{
  "results": [{
    incidentId: ID_OF_INCIDENT,
    detectorId: ID_OF_ORIGINATING_DETECTOR,
    detectLabel: LABEL_OF_ORIGINATING_DETECT_FUNCTION,
    active: WHETHER_INCIDENT_IS_ONGOING,
    severity: INCIDENT_SEVERITY,
    anomalyState: CURRENT_ANOMALY_STATE,
    events: LIST_OF_EVENTS_FOR_INCIDENT,
    duration: DURATION_OF_INCIDENT
  }]
}

Query Params

offset
int32

Offset of results to return

limit
int32

Number of results to return

includeResolved
boolean

Whether to return incidents which have already resolved

 

API supports only v2 detectors

This API is supported only for incidents related to v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/incident/:id

Get incident information for a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/incident/id
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident/ABCDEFGHIJ
A binary file was returned

You couldn't be authenticated

{
	incidentId: ID_OF_INCIDENT,
  detectorId: ID_OF_ORIGINATING_DETECTOR,
  detectLabel: LABEL_OF_ORIGINATING_DETECT_FUNCTION,
  active: WHETHER_INCIDENT_IS_ONGOING,
  severity: INCIDENT_SEVERITY,
  anomalyState: CURRENT_ANOMALY_STATE,
  events: LIST_OF_EVENTS_FOR_INCIDENT,
  duration: DURATION_OF_INCIDENT
}

Path Params

id
string
required
 

API supports only v2 detectors

This API is supported only for incidents related to v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/incident/:id/clear

Manually clear (resolve) an incident

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/incident/id/clear
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident/ABCDEFGHIJ/clear
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required
 

API supports incidents for all detectors

Unlike some incident APIs, this API can be used with incidents related to detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting

Retrieve alert muting rules

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/alertmuting
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

include
string

Types of muting rules to be included (Past, Future, Ongoing, Open, All)

query
string

Query string to search for muting rules

orderBy
array of strings

Fields to sort result by; default is start time in ms since epoch

limit
int32

Number of results to return

offset
int32

Offset of results to return

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting

Create new alert muting rule

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/alertmuting
$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --data-binary @- \
  https://api.signalfx.com/v2/alertmuting << EOF
{
  "startTime": 1473224400050,
  "stopTime": 1473310800050,
  "filters": [{"not": false, "property": "customer", "propertyValue": "abc"}]
}
EOF
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

filters

List of filters. Example of filter {"property":"availabilityZone", "propertyValue":"us-east-1a", "NOT":false}

startTime
int64

Start time of muting period in milliseconds since epoch. If startTime is not specified, it will default its value to the current time in UTC milliseconds.

stopTime
int64

Stop time of muting period in milliseconds since epoch. 0 indicates that the detectors matching this rule will be muted indefinitely. If stopTime is not specified, the value will default to 0.

description

Description of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Retrieve alert muting rule by ID

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/ABCD1234
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the muting rule object

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Update an alert muting rule

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --data-binary @- \
  https://api.signalfx.com/v2/alertmuting/abcd1234 << EOF
{
  "startTime": 1473224400050,
  "stopTime": 1473310800050,
  "filters": [{"not": false, "property": "customer", "propertyValue": "abc"}]
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the muting

Body Params

filters

List of filters. Example of filter {"property":"availabilityZone", "propertyValue":"us-east-1a", "NOT":false}. Example for filter by detector {"property":"sf_detectorId", "propertyValue":"theDetectorId", "NOT":false}

startTime
int64

Start time of muting period in milliseconds since epoch. If startTime is not specified, it will default its value to the current time in UTC milliseconds.

stopTime
int64

Stop time of muting period in milliseconds since epoch. 0 indicates that the detectors matching this rule will be muted indefinitely. If stopTime is not specified, the value will default to 0.

description

Description of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Delete an alert muting rule scheduled to start in the future

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request DELETE \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/abcd1234
A binary file was returned

You couldn't be authenticated

Cannot delete alert muting in the past.
Unable to find the given alert muting.

Path Params

id
string
required

ID of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id/unmute

End a muting period that is currently active. Updates stop time to server current time.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/alertmuting/id/unmute
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/Cqe64MjAAAE/unmute
A binary file was returned

You couldn't be authenticated

{
  "created" : 1471890049324,
  "creator" : "CqewHrdAAAI",
  "description" : "",
  "filters" : [ {
    "NOT" : false,
    "property" : "demo_customer",
    "propertyValue" : "thefountain.org"
  } ],
  "id" : "Cqe64MjAAAE",
  "lastUpdated" : 1471890103224,
  "lastUpdatedBy" : "CqewHrdAAAI",
  "startTime" : 1471890049311,
  "stopTime" : 1471890103193
}
"Cannot update alert muting that has already ended."
Unable to find the given alert muting.

Path Params

id
string
required

Body Params

description

(optional) Text to update the current muting rule description

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

Charts Overview

Charts enable you to visualize the metrics you are sending in to SignalFx

 

Charts enable you to visualize the metrics you are sending in to SignalFx. A metric is anything that is measurable (you can assign a numerical value to it) and variable (changes over time). A chart may contain a single plot or multiple related plots in a single visualization.

Within the web application, every chart belongs to one dashboard which in turn is part of one dashboard group. These are one-to-many relationships; each dashboard may contain multiple charts but each chart belongs to only one dashboard. These relationships are stored in the containing object; charts do not know their associated dashboard but dashboards contain a list of the charts associated with them. However, charts created via API call do not automatically belong to a dashboard; this relationship must be manually set using dashboard API calls. Until that happens, a chart is considered an orphan by the SignalFx web application and will only be accessible via direct request. Charts created by API calls can be directly viewed in the web application using their id property as follows:

https://app.signalfx.com/#/chart/v2/_id_

and will also appear by name in the catalog and in their associated dashboard.

In general, each chart is based on a specified SignalFlow program; users creating or updating charts are expected to understand SignalFlow and be able to create, edit, and interpret statements using it. That said, the SignalFlow associate with a specific chart may be modified by filters associated with its dashboard so the chart definition is not entirely self-contained.

Charts may contain watermarks highlighting regions of interest or high and low threshold values visually indicating when outliers occur.

Types of Charts

SignalFx supports five types of charts:

Single Value Charts

Single value charts show a single data point's value as it changes over time. This type of chart is typically used on wall TV displays (and elsewhere) to display very important single metrics with a low information density. Common examples of single value charts include host counts, the number of active processes, and the number of X served in the past day.

Single Value Chart Example -narrow

Single Value charts typically have no historical context - once the value changes to the next bit of data in the stream the previous values are gone and cannot be restored or viewed again. The current value can be set to display specific colors based on thresholds; for instance when the number of X served in a particular day meets the daily goal the color can be switched from red to green so everyone knows the goal has been met.

If a stream with more than one time series is set to display in a single value chart, the chart will display the first time series it finds and disregard the rest.

Prefix and suffix values can be added to help describe the value being shown on the chart:
Single Value Chart Prefix and Suffix Example -narrow

Single value charts can have sparkline, radial, or linear secondary visualizations in addition to the displayed value; no secondary visualization is used by default. A sparkline visualization shows recent trends of the value, a radial visualization displays a dial indicating where the current value falls among the expected range of values, and a linear visualization displays a bar indicating where the current value falls among the expected range of values.

A single value chart with a sparkline visualization might look like this:
Sparkline Secondary Visualization

A single value chart with a radial visualization might look like this:
Radial Secondary Visualization Example

A single value chart with a linear visualization might look like this:
Linear Secondary Visualization Example

List Charts

List charts are similar to single value charts but they support displaying more than one data point at a time and showing recent trends in the data without the ability to look at the historical data in any detail. They support up to 100 items displayed in the chart simultaneously but work best with 20 or fewer items shown. A common usage for list charts is to display the Top N of something, for example the hosts with the highest CPU usage.

List Chart Example

Values on list charts can be sorted based on criteria chosen by the chart creator, but because the values of any specific metric changes over time, the order they are shown at any given moment changes so the data associated with a specific metric will move around and change order as you scroll.

Prefix and suffix values can be added to help describe the values being shown on the chart:
Line Chart Prefix and Suffix Example

List charts can have sparkline, radial, or linear secondary visualizations for each item in addition to the displayed value or just display the value without a secondary visualization; a sparkline secondary visualization is used by default (see above for an example of what this looks like). A sparkline visualization shows recent trends of the value, a radial visualization displays a dial indicating where the current value falls among the expected range of values, and a linear visualization displays a bar indicating where the current value falls among the expected range of values.

A list chart with a radial visualization might look like this:

Radial Secondary Visualization List Example

A list chart with a linear visualization might look like this:

Linear Secondary Visualization Example

Time Series Charts

Time series charts expand the number of data points that can be displayed at once and retain a larger set of historical data with timestamps to make it easier to locate. Time series charts may include a legend indicating which color represents each value of a particular dimension of a plot. For example, a series of plot lines might be colored by AWS availability zone with red indicating us-east-1, green indicating us-east-2, and purple indicating eu-west-1.

Prefix and suffix values can be added to help describe the values being shown on the chart:
Time Series Chart Prefix and Suffix Example

Time series charts may be visualized in any of four ways: using a line chart, an area chart, a column or bar chart, or a histogram.

Line Charts

The LineChart plot type displays the data in a plot with datapoints connected by a series of straight lines as follows:

Time Series Chart Line Chart Example

Area Charts

The AreaChart plot type displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in as follows:

Time Series Chart Area Chart Example

Column Charts

The ColumnChart plot type lists the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. By default each plot point is shown as an independent bar closely plotted next to each other as follows:

Time Series Chart Column Chart Example

Column charts can also be stacked, meaning that the bars representing each value at each moment in time are stacked vertically on top of each other at the relevant time point along the x-axis rather than being grouped next to each other near that point as follows:

Time Series Chart Stacked Column Chart Example

Histograms

Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar or darker shades of a single color might indicate a higher density of plot points with the relevant value than a higher shade of that same color as follows:

Time Series Chart Histogram Chart Example

The values of a histogram plot display in a random order by default but may be organized into two levels of grouping to hone in on the behavior of specific sets of data. For example, data might be grouped by AWS region or availability zone to make it easier to track performance within each region or availability zone.

Heatmap Charts

Heatmap charts present a series of squares each representing a single data point of the selected metric. The color of each square represents the value range of the metric allowing quick identification of values that are higher or lower than desired.

Heatmap Example

The data points in a heatmap can be grouped by up to two properties to highlight the health of a specific aspect of the data being viewed. For example, the following heatmap groups CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping.


Heatmap Example with Grouping -wide

Prefix and suffix values can be added to help describe the value being shown on the chart:
Heatmap Prefix and Suffix Example

Text Charts

Text charts allow users to add descriptive text or other information to a dashboard. The chart essentially displays any specified GitHub style Markdown within the chart location and is used to provide information about one or more other charts in the same dashboard.

Text Chart Example -wide

Color Palette

Some elements of SignalFx charts are restricted to a color palette of or based on 21 specific colors referenced by a 0-based index.

The default colors represented by the color index are:

Index Hex Value Sample Swatch
0 #999999 color #999999 -wide
1 #0077c2 color #0077c2 -wide
2 #00b9ff color #00b9ff -wide
3 #6ca2b7 color #6ca2b7 -wide
4 #b04600 color #b04600 -wide
5 #f47e00 color #f47e00 -wide
6 #e5b312 color #e5b312 -wide
7 #bd468d color #bd468d -wide
8 #e9008a color #e9008a -wide
9 #ff8dd1 color #ff8dd1 -wide
10 #876ff3 color #876ff3 -wide
11 #a747ff color #a747ff -wide
12 #ab99bc color #ab99bc -wide
13 #007c1d color #007c1d -wide
14 #05ce00 color #05ce00 -wide
15 #0dba8f color #0dba8f -wide
16 #ea1849 color #ea1849 -wide
17 #eac24b color #eac24b -wide
18 #e5e517 color #e5e517 -wide
19 #acef7f color #acef7f -wide
20 #6bd37e color #6bd37e -wide


These colors may be swapped out for colorblind friendly alternatives by users who select such options:

Index Normal Setting Red-Green Colorblind Setting Yellow-Blue Colorblind Setting
0 #999999 #999999 #005160
1 #0077c2 #000982 #007186
2 #00b9ff #0814b6 #0089a2
3 #6ca2b7 #0b1ae4 #00a2c0
4 #b04600 #7c730b #85005e
5 #f47e00 #aba734 #a40074
6 #e5b312 #c5bf1c #c20089
7 #bd468d #dad30a #e400a1
8 #e9008a #535353 #555555
9 #ff8dd1 #787878 #666666
10 #876ff3 #b0b0b0 #787878
11 #a747ff #c1c1c1 #888888
12 #ab99bc #bc82b6 #999999
13 #007c1d #b36dac #aaaaaa
14 #05ce00 #b241a6 #bbbbbb
15 #0dba8f #b0009d #cccccc
16 #ea1849 #b0009d #e400a1
17 #eac24b #7c730b #005160
18 #e5e517 #aba734 #007186
19 #acef7f #c5bf1c #0089a2
20 #6bd37e #c1c1c1 #c1c1c1

This will happen automatically and is not configurable by developers via API settings.

Suggest Edits

Create Chart

The Create Chart API call creates a new v2 chart.

 

The Create Chart API call creates a new v2 chart. Before the chart has real context in the web application, it must be added to a dashboard using one of the Create Dashboard or Update Dashboard API calls. Once it belongs to a dashboard, the chart will appear within that dashboard and be individually viewable via the chart v2 interface (which may be slightly different from the v1 chart interface described in the SignalFx web application documentation here). It will also be listed by name in the chart section of the catalog for the relevant organization.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

POST https://api.signalfx.com/v2/chart

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Chart call:

Property Type Constraints Description
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string None The description of the chart. This value appears underneath the chart name in the SignalFx web application.
name string
  • required
  • minimum characters = 1
The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first. It may be desirable to use unique names for charts but this is not enforced by the API.
options object
  • default values as indicated in specific properties of the object
The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object
  • Only available if the options.type property is set to TimeSeriesChart
The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean
  • Only available if the options.type property is set to TimeSeriesChart
  • Default value is false
When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects
  • Only available if the options.type property is set to TimeSeriesChart
Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or less than the value of the options.axes[x].max property of the same element
  • Value must be greater than the value of the options.axes[x].lowWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string
  • Only available if the options.type property is set to TimeSeriesChart
A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or greater than the value of the options.axes[x].min property of the same element
  • Value must be less than the value of the options.axes[x].highWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart.
options.axes[x].min float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be less than the value of the options.axes[x].max property of the same element
Indicates the smallest value to display on the chart.
options.axisPrecision integer
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be an integer between 3 and 10
  • Value is 3 by default
Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string
  • Not available if the options.type property is set to Text
  • If the options.type property is set to Heatmap:
    • Supported values are: Range and Scale
    • Default value is Range
  • If the options.type property is set to List:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to SingleValue:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to TimeSeriesChart:
    • Supported values are: Dimension and Metric
    • Default value is Dimension
Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object
  • Only available if the options.type property is set to Heatmap
The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string
  • Only available if the options.type property is set to Heatmap
  • Expected to have seven characters as follows:
    • The first character is always a pound sign ("#")
    • The other characters may be any numeral or a capital letter between A and F inclusive
The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string
  • Only available if the options.type property is set to Heatmap
The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string
  • Only available if the options.type property is set to Heatmap
The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean
  • Available if the options.type property is set to Heatmap, SingleValue, or List
  • Set to false by default
If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects
  • Available if the options.type property is set to List, SingleValue, or Heatmap
Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
  • Required
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
  • Default value is LineChart
Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings
  • Available if the options.type property is set to Heatmap
Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.legendOptions object
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default value is true
Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string
  • Available if the options.type property is set to TimeSeriesChart or List
The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlot.type property is set to LineChart
Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean
  • Available if the is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
  • Default value is false
Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string
  • Only available if the options.type property is set to Text
The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer
  • Only available if the options.type property is set to List or SingleValue
  • Value must be an integer
Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object
  • Available if the options.type property is set to TimeSeriesChart
Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string
  • Available if the options.type property is set to TimeSeriesChart
Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object
  • Available if the options.type property is set to anything but Text
General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean
  • Available if the options.type property is set to anything but Text
  • Default is false.
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
  • Required
Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value =20
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].valueSuffix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].yAxis integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 1
Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer
  • Available if the options.type property is set to List or SingleValue
Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string
  • Available if the options.type property is set to List or SingleValue
  • Supported Values are: None, Radial, Linear, Sparkline.
  • If the options.type property is set to List:
    • Default value is Sparkline
  • If options.type property is set to SingleValue:
    • Default value is None
Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean
  • Available if the options.type property is set to SingleValue
  • Default is false
If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortDirection enumerated string
  • Available if the options.type property is set to Heatmap
  • Supported values are: Ascending and Descending
  • Default value is Ascending
Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string
  • Available if the options.type property is set to Heatmap
The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to AreaChart or ColumnChart
  • Default is false
If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.time object
  • Available if the options.type property is set to TimeSeriesChart
Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
options.time.start integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string
  • Available if the options.type property is set to TimeSeriesChart
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean
  • Available if the options.type property is set to Heatmap or SingleValue
  • Default is false
If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string
  • Required
  • Supported values are: Heatmap, List, SingleValue, Text, TimeSeriesChart
The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string
  • Available if the options.type property is set to anything but Text
  • Supported values are: Binary and Metric
  • Default value is Metric
Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string
  • Value must be signalfx
Indicates one or more SignalFlow packages to import for use in the programText value. Currently the only the signalfx package is available.
programText string
  • required for all chart types except Text
A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Chart call:

Property Type Contexts Returned Description
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to the chart object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer options.type property=List, SingleValue, or Heatmap Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer options.type property=TimeSeriesChart, List, or SingleValue Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Charts

The Get Charts API retrieves one or more v2 charts identified by optional search criteria.

 

The Get Charts API retrieves one or more v2 charts identified by optional search criteria. If no search criteria is specified, the first 50 charts visible to the user are returned. Paging of results is controlled using the offset and limit path parameters to specify the starting point of the results and the maximum number of results to return respectively. See the path parameter documentation below for more information on search criteria and paging.

For more information on charts including the types of charts supported and the different ways they can be visualized, see Charts Overview.

Syntax

GET https://api.signalfx.com/v2/chart[?[name=_chartName_][&][_tagSpecification_][&][offset=_startValue_][&][limit=_requestedNumberReturned_]]

where tagSpecification has the following syntax:

tags=tag1[&tags=tag2][&....tags=tagK]

NOTE: [content] indicates that content is an optional block that may or may not be needed depending on the desired query

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Charts call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Query Parameters

The Get Charts API call supports the following query parameters as indicated in the syntax line above:

Parameter Value Type Constraints Description
limit integer
  • Default=50
  • minimum value=1
The maximum number of objects to return in the response. Unrecognized values are ignored and result in the default value of 50 being used.
name string
  • minimum characters=1
a search string acting as a full or partial match to the value in the name property of chart objects. Any UTF-8 characters may be included in the search string and strings will match against any portion of the name property; for example, name=per will match all of the following names:
  • ..... dropped per day...
  • ...95th percentile
  • personal disk usage...
offset integer
  • Default=0
  • minimum value=0
The starting index value of the returned objects; this assumes all of the possible returns are put in a 0-based indexed list in the appropriate sort order and identified by their order in the list. If the offset value is greater than the number of possible results, no objects are returned in the response.
tags string
  • Parameter is repeatable
a search string acting as a full or partial match to an element in the tags array property of chart objects. Any UTF-8 characters may be included in the search strings and strings will match against any portion of the value of any element in the tags array; for example tags=dat will match all of the following tags:
  • data
  • date
  • datetime
  • metadata

Payload

The Get Charts API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Charts call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Charts call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Charts call:

Property Type Contexts Returned Description
count integer All Indicates the number of objects that match the search query. It does not provide any information on the number of objects actually returned in the request; if paging is employed the number of objects should be equivalent to either the value of the limit path parameter or the remainder of the objects after the supplied value of the offset parameter.
results list of objects List of chart objects matching the request criteria. The properties of the included results objects are indicated as results[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the results array.
results[x].created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
results[x].creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
results[x].description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
results[x].id string All The ID assigned to the chart object. This ID is unique and always set by the system.
results[x].lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
results[x].lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
results[x].options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as results[x].options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
results[x].options.areaChartOptions object results[x].options.type property=TimeSeriesChart The area chart options applied to this chart. The properties of the included options object are indicated as results[x].options.areaChartOptions.propertyName in this documentation.
results[x].options.areaChartOptions.showDataMarkers boolean results[x].options.type property=TimeSeriesChart When true, markers will be drawn for each datapoint within the visualization.
results[x].options.axes list of objects results[x].options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as results[x].options.axes[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
results[x].options.axes[y].highWatermark float results[x].options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
results[x].options.axes[y].label string results[x].options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
results[x].options.axes[y].lowWatermark float results[x].options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
results[x].options.axes[y].max float results[x].options.type property = TimeSeriesChart Indicates the largest value to display on the chart.
results[x].options.axes[y].min float results[x].options.type property=TimeSeriesChart Indicates the smallest value to display on the chart.
results[x].options.axisPrecision integer results[x].options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
results[x].options.colorBy enumerated string results[x].options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
results[x].options.colorRange object results[x].options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as results[x].options.colorRange.propertyName in this documentation.
results[x].options.colorRange.color string results[x].options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
results[x].options.colorRange.max string results[x].options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
results[x].options.colorRange.min string results[x].options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
results[x].options.colorScale object results[x].options.type property=Heatmap or SingleValue Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If results[x].options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as results[x].options.colorScale.propertyName in this documentation.
results[x].options.colorScale.inverted boolean results[x].options.type property=Heatmap or SingleValue If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using results[x].options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
results[x].options.colorScale.thresholds list of floats results[x].options.type property=Heatmap or SingleValue Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
results[x].options.colorScale2 list of objects results[x].options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as results[x].options.colorScale2[y].propertyName in this documentation.
results[x].options.colorScale2[y].gt float results[x].options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
results[x].options.colorScale2[y].gte float results[x].options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
results[x].options.colorScale2[y].lt float results[x].options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
results[x].options.colorScale2[y].lte float results[x].options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
results[x].options.colorScale2[y].paletteIndex integer results[x].options.type property=List, SingleValue, or Heatmap Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
results[x].options.defaultPlotType enumerated string results[x].options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
results[x].options.groupBy list of strings results[x].options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the results[x].customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
results[x].options.legendOptions object results[x].options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as results[x].options.legendOptions.propertyName in this documentation.
results[x].options.legendOptions.fields list of objects results[x].options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as results[x].options.legendOptions.fields[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
results[x].options.legendOptions.fields[y].enabled boolean results[x].options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
results[x].options.legendOptions.fields[y].property string results[x].options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
results[x].options.lineChartOptions object results[x].options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as results[x].options.lineChartOptions.propertyName in this documentation.
results[x].options.lineChartOptions.showDataMarkers boolean results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType property =LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
results[x].options.markdown string results[x].options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
results[x].options.maximumPrecision integer results[x].options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
results[x].options.onChartLegendOptions object results[x].options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as results[x].options.onChartLegendOptions.propertyName in this documentation.
results[x].options.onChartLegendOptions.dimensionInLegend string results[x].options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
results[x].options.onChartLegendOptions.showLegend boolean results[x].options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the results[x].options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
results[x].options.programOptions object results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as results[x].options.programOptions.propertyName in this documentation.
results[x].options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
results[x].options.programOptions.maxDelay integer results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
results[x].options.programOptions.minimumResolution integer results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
results[x].options.publishLabelOptions list of objects results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as results[x].options.publishLabelOptions[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
results[x].options.publishLabelOptions[y].displayName string results[x].options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
results[x].options.publishLabelOptions[y].label string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
results[x].options.publishLabelOptions[y].paletteIndex integer results[x].options.type property=TimeSeriesChart, List, or SingleValue Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
results[x].options.publishLabelOptions[y].plotType enumerated string results[x].options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of results[x].options.defaultPlotType for the output of this SignalFlow statement.
results[x].options.publishLabelOptions[y].valuePrefix string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
results[x].options.publishLabelOptions[y].valueSuffix string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
results[x].options.publishLabelOptions[y].yAxis integer results[x].options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
results[x].options.refreshInterval integer results[x].options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string results[x].options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
results[x].options.showEventLines boolean results[x].options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
results[x].options.showSparkLine boolean results[x].options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if results[x].options.secondaryVisualization is set.
results[x].options.sortDirection enumerated string results[x].options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
results[x].options.sortProperty string results[x].options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
results[x].options.stacked boolean results[x].options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
results[x].options.time object results[x].options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as results[x].options.time.propertyName in this documentation.
results[x].options.time.end integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
results[x].options.time.range integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
results[x].options.time.start integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
results[x].options.time.type enumerated string results[x].options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
results[x].options.timestampHidden boolean results[x].options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
results[x].options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
results[x].options.unitPrefix enumerated string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
results[x].packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
results[x].programText string results[x].option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
results[x].tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Chart

The Get Chart API retrieves a single v2 chart identified by its id value.

 

The Get Chart API retrieves a single v2 chart identified by its id value. This API call only supports v2 chart objects; an error will be thrown if you try to retrieve a v1 chart object.

For more information on charts including the types of charts supported and the different ways they can be visualized, see Charts Overview.

Syntax

GET https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Get Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing chart object.

Payload

The Get Chart API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Chart call:

Property Type Contexts Returned Description
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to the chart object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer options.type property=List, SingleValue, or Heatmap Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer options.type property=TimeSeriesChart, List, or SingleValue Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string All Indicates one or more Signal Flow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Update Chart

The Update Chart API call modifies an existing v2 chart identified by its id value.

 

The Update Chart API call modifies an existing v2 chart identified by its id value.

The Update Chart call is a full update; any properties not included in the update call will be removed or reset to their default state. In particular, if you change the type of the chart, those properties that do not apply to the new chart type will be removed. If you later change the chart back to the original type, the previous values are not retained and must be resent in the update call if desired.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

PUT https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Update Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Update Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing chart object to modify.

Payload

The following properties are supported in the request payload for the Update Chart call:

Property Type Constraints Description
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string None The description of the chart. This value appears underneath the chart name in the SignalFx web application.
name string
  • required
  • minimum characters = 1
The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first. It may be desirable to use unique names for charts but this is not enforced by the API.
options object
  • default values as indicated in specific properties of the object
The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object
  • Only available if the options.type property is set to TimeSeriesChart
The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean
  • Only available if the options.type property is set to TimeSeriesChart
  • Default value is false
When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects
  • Only available if the options.type property is set to TimeSeriesChart
Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or less than the value of the options.axes[x].max property of the same element
  • Value must be greater than the value of the options.axes[x].lowWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string
  • Only available if the options.type property is set to TimeSeriesChart
A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or greater than the value of the options.axes[x].min property of the same element
  • Value must be less than the value of the options.axes[x].highWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart.
options.axes[x].min float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be less than the value of the options.axes[x].max property of the same element
Indicates the smallest value to display on the chart.
options.axisPrecision integer
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be an integer between 3 and 10
  • Value is 3 by default
Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string
  • Not available if the options.type property is set to Text
  • If the options.type property is set to Heatmap:
    • Supported values are: Range and Scale
    • Default value is Range
  • If the options.type property is set to List:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to SingleValue:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to TimeSeriesChart:
    • Supported values are: Dimension and Metric
    • Default value is Dimension
Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object
  • Only available if the options.type property is set to Heatmap
The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string
  • Only available if the options.type property is set to Heatmap
  • Expected to have seven characters as follows:
    • The first character is always a pound sign ("#")
    • The other characters may be any numeral or a capital letter between A and F inclusive
The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string
  • Only available if the options.type property is set to Heatmap
The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string
  • Only available if the options.type property is set to Heatmap
The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean
  • Available if the options.type property is set to Heatmap, SingleValue, or List
  • Set to false by default
If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects
  • Available if the options.type property is set to List, SingleValue, or Heatmap
Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
  • Required
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
  • Default value is LineChart
Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings
  • Available if the options.type property is set to Heatmap
Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.legendOptions object
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default value is true
Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string
  • Available if the options.type property is set to TimeSeriesChart or List
The key name of a customProperty specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlot.type property is set to LineChart
Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean
  • Available if the is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
  • Default value is false
Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string
  • Only available if the options.type property is set to Text
The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer
  • Only available if the options.type property is set to List or SingleValue
  • Value must be an integer
Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object
  • Available if the options.type property is set to TimeSeriesChart
Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string
  • Available if the options.type property is set to TimeSeriesChart
Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object
  • Available if the options.type property is set to anything but Text
General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean
  • Available if the options.type property is set to anything but Text
  • Default is false.
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
  • Required
Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value =20
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].valueSuffix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].yAxis integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 1
Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer
  • Available if the options.type property is set to List or SingleValue
Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string
  • Available if the options.type property is set to List or SingleValue
  • Supported Values are: None, Radial, Linear, Sparkline.
  • If the options.type property is set to List:
    • Default value is Sparkline
  • If options.type property is set to SingleValue:
    • Default value is None
Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean
  • Available if the options.type property is set to SingleValue
  • Default is false
If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortDirection enumerated string
  • Available if the options.type property is set to Heatmap
  • Supported values are: Ascending and Descending
  • Default value is Ascending
Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string
  • Available if the options.type property is set to Heatmap
The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to AreaChart or ColumnChart
  • Default is false
If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.time object
  • Available if the options.type property is set to TimeSeriesChart
Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
options.time.start integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string
  • Available if the options.type property is set to TimeSeriesChart
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean
  • Available if the options.type property is set to Heatmap or SingleValue
  • Default is false
If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string
  • Required
  • Supported values are: Heatmap, List, SingleValue, Text, TimeSeriesChart
The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string
  • Available if the options.type property is set to anything but Text
  • Supported values are: Binary and Metric
  • Default value is Metric
Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string
  • Value must be signalfx
Indicates one or more SignalFlow packages to import for use in the programText value. Currently the only the signalfx package is available.
programText string
  • required for all chart types except Text
A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Update Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Update Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Update Chart call:

Property Type Contexts Returned Description
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to chart object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer options.type property=List, SingleValue, or Heatmap Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a customProperty specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer options.type property=TimeSeriesChart, List, or SingleValue Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto. This property will be overridden if options.secondaryVisualization is set.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Delete Chart

The Delete Chart API permanently deletes a single v2 chart identified by its id value.

 

The Delete Chart API permanently deletes a single v2 chart identified by its id value.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

DELETE https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Delete Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Delete Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing Chart object.

Payload

The Delete Chart API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Delete Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Delete Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Delete Chart API call does not send a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Dashboards Overview

Dashboards are a grouping of charts organized to display together and subject to the same filtering options.

 

Dashboards are a grouping of charts organized to display together and subject to the same filtering options. Dashboards are a 12x100 grid with one or more charts assigned to specific grid locations. A chart associated with the dashboard may be any size from 1x1 to 12x3; if charts are assigned overlapping dashboard locations an attempt to resize or automatically reorganize the layout is made to ensure all of charts fit within the allotted space.

Every dashboard must belong to a dashboard group. This is a one-to-many relationship; each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards. If an existing dashboard group is not specified when a dashboard is created, a container dashboardgroup object is also created for the new dashboard object. Although the dashboard group ID is stored in the dashboard to ensure that one exists, the dashboard group -> dashboard relationship is officially managed by the containing dashboard group; the dashboards property of the associated dashboardgroup object is the system of record for determining which dashboards belong to which dashboard group. For more information on dashboard groups, see the Dashboard Groups Overview.

Similarly, the dashboard object is the system of record for the one-to-many dashboard->charts relationship. The relationship itself is stored in the charts property and many of the other properties of a dashboard object are designed to control the display of the underlying charts associated with the dashboard. For more information about charts, see the Charts Overview. More information about the specific properties of the dashboard object can be found in the payload sections of individual API calls.

Existing dashboards can also be cloned into additional dashboard groups with or without minor modifications. Any dashboard can be cloned including built-in dashboards and user specific dashboards. If you test or develop new dashboards in your user specific dashboard group, you would promote them to production when ready using a Clone Dashboard into Dashboard Group call. Similarly, if you want to modify a built-in dashboard to better suit your needs you would clone it first then edit the cloned version however you wish.

When a dashboard is deleted, the underlying charts are orphaned. They are essentially in the same state as when they are newly created and may be added to a new dashboard if desired. However, when a dashboard group is deleted, the underlying dashboards are automatically deleted as well, as are the charts associated with those dashboards.

Dashboards created by API calls can be directly viewed in the web application using their id property as follows:

https://app.signalfx.com/#/dashboard/_id_

and will also appear by name in the catalog and in their associated dashboard group.

Types of Dashboards

SignalFx supports three types of dashboards:

Built-in Dashboards

Built-in dashboards are not editable but are returned in Get Dashboard and Get Dashboards calls. Built-in dashboards all have their creator property set to the system user ID "AAAAAAAAAAA".

In addition, these dashboards typically have descriptive names and descriptions.

The charts associated with built-in dashboards are all v1 charts and are not accessible via SignalFx API calls. To interact with these charts you must use the web application.

Every organization starts with dashboards related to their organization and a set of dashboards with sample data. Additional built-in dashboards are added with each integration added to the organization.

User Default Dashboards

Part of the new user account creation process involves setting up a new dashboard (and associated new dashboard group) for that user. This dashboard is a place where that user can experiment, develop, and tweak dashboards before they're ready for wider use.

User default dashboards are created automatically when a user is invited to an organization and can be updated after creation. They are returned in Get Dashboard and Get Dashboards calls and can be identified as follows:

  • The name of the dashboard is the email address of the associated user
  • The description of the dashboard is "Default dashboard."
  • The creator property of the dashboard is set to the associated user's ID (instead of the system user ID used for most actions taken directly by the system)
  • The chartDensity property is set to DEFAULT
  • All other user-settable properties are null by default

NOTE: Every user in the organization has the ability to edit every user's default dashboard. We strongly recommend that each user manage their own user default dashboard and that users only modify their own user dashboard not those associated with other users in the organization but this is not enforced by the system.

Custom Dashboards

All dashboards created via the SignalFx API are custom dashboards. These are the production dashboards used by an organization to monitor their systems. There are two types of custom dashboards:

Standard Dashboards

Standard Dashboards are created using the Create Dashboard API call and provide full control of the number of included charts and their layout to their creator. They also support filters and event overlays for finer control over the chart data displayed within the dashboard. Standard dashboards are typically references just as dashboards with no additional qualifier.

Simple Dashboards

Simple Dashboards are dashboards created using the Create Simple Dashboard API call. This submits new chart object definitions without any additional information. These chart definitions are turned into new chart objects and added to a new dashboard in a new dashboard group using a default layout. The resulting simple dashboard contains no filters or event overlays.

Once created, a simple dashboard is indistinguishable from a standard dashboard that doesn't define filters or event overlays and that uses the default simple dashboard layout rules; both types of dashboards are stored in the dashboard object type. If desired, layout adjustments can be made and filters and event overlays can be added to simple dashboards using Update Dashboard calls. However, the expectation is that dashboards requiring significant deviation from the simple dashboard defaults will be created as standard dashboards.

Suggest Edits

Create Dashboard

The Create Dashboard API call creates a new v2 dashboard object.

 

The Create Dashboard API call creates a new v2 dashboard object. Dashboards act as a container for one or more charts to be displayed in a single view in the web application. In turn, dashboards are contained within dashboard groups that link similar or related groups together in the web application.

Every dashboard must belong to a dashboard group. This is a one-to-many relationship; each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards. If an existing dashboard is not specified in the groupId property of the Create Dashboard request payload, a container dashboardgroup object is also created for the new dashboard object. Automatically created dashboardgroup objects will use the same name as the dashboard generating its creation, have an empty string for its description, and set the user ID associated with the Create Dashboard call as its creator; its ID will be returned in the groupId property of the response to the Create Dashboard call. Although the dashboard group ID is stored in the dashboard to ensure that one exists, the dashboard group -> dashboard relationship is officially managed by the containing dashboard group and the dashboards property of the associated dashboardgroup object is the system of record for determining which dashboards belong to which dashboard group. The dashboards property of an automatically created dashboardgroup object will contain the ID of the new dashboard it was created to contain.

Once created, a dashboard will appear within its dashboard group in the web application and be individually viewable via the dashboard interface described in the SignalFx web application documentation here. It will also be listed by name in the dashboard section of the catalog for the relevant organization.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

POST https://api.signalfx.com/v2/dashboard

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Dashboard call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Dashboard call:

Property Type Constraints Description
chartDensity enumerated string
  • Supported values are: DEFAULT, LOW, HIGH, HIGHEST
  • Default value is DEFAULT
Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects None An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string
  • Required
  • Must map to a valid chart object
  • Must be unique across all dashboards
The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer
  • Required
  • Minimum value = 0
  • Maximum value = 11
A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer
  • Required
  • Minimum value = 1
  • Maximum value = 3
The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer
  • Required
  • Minimum value = 0
  • Maximum value = 99
A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer
  • Required
  • Minimum value = 1
  • Maximum value = 12
The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
Reserved for future use
description string
  • Default is empty string
A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
eventOverlays list of objects None A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean
  • Default is false
Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvent and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer
  • Default value=0
The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string None The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object None A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects
  • Must contain at least one element if specified
Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object None The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer
  • Must be an integer if filters.time.start is an integer
  • Must be a string if filters.time.start is a string
  • If integer:
    • Minimum value = 0
    • Value must be larger than value of filters.time.start
  • If string:
    • Allowed value is Now
The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer
  • Must be an integer if filters.time.end is an integer
  • Must be a string if filters.time.end is a string
  • If integer:
    • Minimum value = 0
    • Value must be smaller than value of filters.time.end
  • If string:
    • Value must start with a negative sign
    • A positive integer must follow the negative sign
    • Value must end with a units indicator. Allowed units indicators are m, h, d, w representing minutes, hours, days, and weeks respectively
The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects
  • Must contain at least one element if specified
A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string
  • Required
The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings None A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean
  • Default is false
If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean
  • Default is false
If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings
  • Must contain at least one element if specified
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string None The ID of the dashboard group to associate with this dashboard. If no value is supplied a new dashboard group is created and its ID is assigned to this property as part of processing the create request.
name string
  • Required
  • Minimum characters = 1
The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects None A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvent and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Dashboard call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Dashboard call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Dashboard call:

Property Type Contexts Returned Description
chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All Reserved for future use
description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
discoveryOptions object All Reserved for system use.
eventOverlays list of objects All A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object All A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects All Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object All The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer All The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer All The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects All A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string All The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings All A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean All If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean All If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string All The ID of the dashboard group to associate with this dashboard. If no value is supplied a new dashboard group is created and its ID is assigned to this property as part of processing the create request.
id string All The ID assigned to the dashboard object. If no value is supplied at creation a new dashboard is created and assigned to this dashboard group. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the dashboard cannot be modified in any way. If false, any user with access to the dashboard may edit it.
name string All The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects All A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
tags list of strings All Reserved for future use.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Create Simple Dashboard

The Create Simple Dashboard creates a new v2 dashboard object with a predefined default layout and no filters as well as associated dashboardgroup and chart objects.

 

The Create Simple Dashboard API call creates a new v2 dashboard object. Dashboards act as a container for one or more charts to be displayed in a single view in the web application. In turn, dashboards are contained within dashboard groups that link similar or related groups together in the web application.

The Create Simple Dashboard call takes a set of supplied chart object definitions, creates v2 chart objects from them, and assigns those charts to a newly created v2 dashboard object belonging to a newly created dashboard group. Only the chart definitions are supplied in the request payload; no dashboard layout information, filters, or event overlays can be supplied for simple dashboards.

The request is sent as a series of chart objects inside an array; there is no overarching request object. Each requested chart complies fully with the normal definition of a chart object and may be sent with any valid combination of property values.

For more information on charts including the type of charts, see the Charts Overview .

Once created, a new dashboard containing the specified charts in rows of two will appear within the new dashboard group in the web application and be individually viewable via the dashboard interface described in the SignalFx web application documentation here. It will also be listed by name in the dashboard section of the catalog for the relevant organization. The new charts will also be visible in the chart section of the catalog.

The dashboard objects created by a Create Simple Dashboard call are indistinguishable from those created by normal Create Dashboard calls that don't define filters or event overlays and that use the default simple dashboard layout rules. These objects can be retrieved, updated, or deleted using the normal dashboard API calls for these actions. The chart layout can be modified and filters and event overlays can be added. Similarly, the chart objects created by a Create Simple Dashboard call are indistinguishable from those created by normal Create Chart calls and may be retrieved, updated, or deleted using the normal chart API calls for these actions.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

POST https://api.signalfx.com/v2/dashboard/simple

Request Format

The request consists of the call path above, HTTP headers, and a JSON array payload in the body. This payload must be an array of objects; request payloads containing a single JSON object will be rejected.

Headers

The following HTTP headers are required for the Create Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported within each object in the request payload array for the Create Simple Dashboard call:

Property Type Constraints Description
[x].customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
[x].description string None The description of the chart. This value appears underneath the chart name in the SignalFx web application.
[x].name string
  • required
  • minimum characters = 1
The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first. It may be desirable to use unique names for charts but this is not enforced by the API.
[x].options object
  • default values as indicated in specific properties of the object
The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as [x].options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
[x].options.areaChartOptions object
  • Only available if the [x].options.type property is set to TimeSeriesChart
The area chart options applied to this chart. The properties of the included options object are indicated as [x].options.areaChartOptions.propertyName in this documentation.
[x].options.areaChartOptions.showDataMarkers boolean
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Default value is false
When true, markers will be drawn for each datapoint within the visualization.
[x].options.axes list of objects
  • Only available if the [x].options.type property is set to TimeSeriesChart
Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as [x].options.axes[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
[x].options.axes[y].highWatermark float
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Value must be equal to or less than the value of the [x].options.axes[y].max property of the same element
  • Value must be greater than the value of the [x].options.axes[y].lowWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
[x].options.axes[y].label string
  • Only available if the [x].options.type property is set to TimeSeriesChart
A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
[x].options.axes[y].lowWatermark float
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Value must be equal to or greater than the value of the [x].options.axes[y].min property of the same element
  • Value must be less than the value of the [x].options.axes[y].highWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
[x].options.axes[y].max float
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the [x].options.axes[y].min property of the same element
Indicates the largest value to display on the chart.
[x].options.axes[y].min float
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Value must be less than the value of the [x].options.axes[y].max property of the same element
Indicates the smallest value to display on the chart.
[x].options.axisPrecision integer
  • Only available if the [x].options.type property is set to TimeSeriesChart
  • Value must be an integer between 3 and 10
  • Value is 3 by default
Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
[x].options.colorBy enumerated string
  • Not available if the [x].options.type property is set to Text
  • If the [x].options.type property is set to Heatmap:
    • Supported values are: Range and Scale
    • Default value is Range
  • If the [x].options.type property is set to List:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the [x].options.type property is set to SingleValue:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the [x].options.type property is set to TimeSeriesChart:
    • Supported values are: Dimension and Metric
    • Default value is Dimension
Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
[x].options.colorRange object
  • Only available if the [x].options.type property is set to Heatmap
The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as [x].options.colorRange.propertyName in this documentation.
[x].options.colorRange.color string
  • Only available if the [x].options.type property is set to Heatmap
  • Expected to have seven characters as follows:
    • The first character is always a pound sign ("#")
    • The other characters may be any numeral or a capital letter between A and F inclusive
The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
[x].options.colorRange.max string
  • Only available if the [x].options.type property is set to Heatmap
The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
[x].options.colorRange.min string
  • Only available if the [x].options.type property is set to Heatmap
The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
[x].options.colorScale object
  • Available if the [x].options.type property is set to Heatmap, SingleValue, or List
Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If [x].options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
[x].options.colorScale.inverted boolean
  • Available if the [x].options.type property is set to Heatmap, SingleValue, or List
  • Set to false by default
If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
[x].options.colorScale.thresholds list of floats
  • Available if the [x].options.type property is set to Heatmap, SingleValue, or List
Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
[x].options.colorScale2 list of objects
  • Available if the [x].options.type property=SingleValue, List, or Heatmap
Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as [x].options.colorScale2[y].propertyName in this documentation.
[x].options.colorScale2[y].gt float
  • Available if the [x].options.type property=SingleValue, List, or Heatmap
  • Value must be less than the value of the [x].options.colorScale2[y].lt or [x].options.colorScale2[y].lte property of the same element
  • Cannot have both [x].options.colorScale2[y].gt and [x].options.colorScale2[y].gte set at the same time
Indicates the lower threshold non-inclusive value for this range.
[x].options.colorScale2[y].gte float
  • Available if the [x].options.type property=SingleValue, List, or Heatmap
  • Value must be less than the value of the [x].options.colorScale2[y].lt or [x].options.colorScale2[y].lte property of the same element
  • Cannot have both [x].options.colorScale2[y].gt and [x].options.colorScale2[y].gte set at the same time
Indicates the lower threshold inclusive value for this range.
[x].options.colorScale2[y].lt float
  • Available if the [x].options.type property=SingleValue, List, or Heatmap
  • Value must be less than the value of the [x].options.colorScale2[y].gt or [x].options.colorScale2[y].gte property of the same element
  • Cannot have both [x].options.colorScale2[y].lt and [x].options.colorScale2[y].lte set at the same time
Indicates the upper threshold non-inculsive value for this range.
[x].options.colorScale2[y].lte float
  • Available if the [x].options.type property=SingleValue, List, or Heatmap
  • Value must be less than the value of the [x].options.colorScale2[y].gt or [x].options.colorScale2[y].gte property of the same element
  • Cannot have both [x].options.colorScale2[y].lt and [x].options.colorScale2[y].lte set at the same time
Indicates the upper threshold inclusive value for this range.
[x].options.colorScale2[y].paletteIndex integer
  • Available if the [x].options.type property=List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
  • Required
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
[x].options.defaultPlotType enumerated string
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
  • Default value is LineChart
Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
[x].options.groupBy list of strings
  • Available if the [x].options.type property is set to Heatmap
Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
[x].options.legendOptions object
  • Available if the [x].options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
[x].options.legendOptions.fields list of objects
  • Available if the [x].options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as [x].options.legendOptions.fields[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
[x].options.legendOptions.fields[y].enabled boolean
  • Available if the [x].options.type property is set to TimeSeriesChart or List
  • Default value is true
Indicates whether the associated property is shown (true) or hidden (false) in the data table.
[x].options.legendOptions.fields[y].property string
  • Available if the [x].options.type property is set to TimeSeriesChart or List
The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
[x].options.lineChartOptions object
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlot.type property is set to LineChart
Sets options specific to a line chart. The properties of the included object are indicated as [x].options.lineChartOptions.propertyName in this documentation.
[x].options.lineChartOptions.showDataMarkers boolean
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
  • Default value is false
Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
[x].options.markdown string
  • Only available if the [x].options.type property is set to Text
The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
[x].options.maximumPrecision integer
  • Only available if the [x].options.type property is set to List or SingleValue
  • Value must be an integer
Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
[x].options.onChartLegendOptions object
  • Available if the [x].options.type property is set to TimeSeriesChart
Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as [x].options.onChartLegendOptions.propertyName in this documentation.
[x].options.onChartLegendOptions.dimensionInLegend string
  • Available if the [x].options.type property is set to TimeSeriesChart
Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
[x].options.onChartLegendOptions.showLegend boolean
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Default is false
If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the [x].options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
[x].options.programOptions object
  • Available if the [x].options.type property is set to anything but Text
General options applied to the chart. The properties of the included object are indicated as [x].options.programOptions.propertyName in this documentation.
[x].options.programOptions.disableSampling boolean
  • Available if the [x].options.type property is set to anything but Text
  • Default is false.
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
[x].options.programOptions.maxDelay integer
  • Available if the [x].options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
[x].options.programOptions.minimumResolution integer
  • Available if the [x].options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
[x].options.publishLabelOptions list of objects
  • Available if the [x].options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as [x].options.publishLabelOptions[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
[x].options.publishLabelOptions[y].displayName string
  • Available if the [x]options.type property is set to TimeSeriesChart, List, or SingleValue
Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
[x].options.publishLabelOptions[y].label string
  • Available if the [x].options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
  • Required
Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
[x].options.publishLabelOptions[y].paletteIndex integer
  • Available if the [x].options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value =20
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
[x].options.publishLabelOptions[y].plotType enumerated string
  • Available if the [x].options.type property is set to TimeSeriesChart, List, or SingleValue
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
Overrides the value of [x].options.defaultPlotType for the output of this SignalFlow statement.
[x].options.publishLabelOptions[y].valuePrefix string
  • Available if the [x].options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
[x].options.publishLabelOptions[y].valueSuffix string
  • Available if the [x].options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview.
[x].options.publishLabelOptions[y].yAxis integer
  • Available if the [x].options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 1
Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
[x].options.refreshInterval integer
  • Available if the [x].options.type property is set to List or SingleValue
Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
[x].options.secondaryVisualization enumerated string
  • Available if the [x]options.type property is set to List or SingleValue
  • Supported Values are: None, Radial, Linear, Sparkline.
  • If the [x].options.type property is set to List:
    • Default value is Sparkline
  • If [x].options.type property is set to SingleValue:
    • Default value is None
Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
[x].options.showEventLines boolean
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Default is false
If true, a vertical line is displayed on the chart when an event is triggered.
[x].options.showSparkLine boolean
  • Available if the [x].options.type property is set to SingleValue
  • Default is false
If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if [x].options.secondaryVisualization is set.
[x].options.sortDirection enumerated string
  • Available if the [x].options.type property is set to Heatmap
  • Supported values are: Ascending and Descending
  • Default value is Ascending
Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
[x].options.sortProperty string
  • Available if the [x].options.type property is set to Heatmap
The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
[x].options.stacked boolean
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the [x].options.defaultPlotType property is set to AreaChart or ColumnChart
  • Default is false
If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
[x].options.time object
  • Available if the [x].options.type property is set to TimeSeriesChart
Options for the time displayed on the chart. The properties of the included object are indicated as [x].options.time.propertyName in this documentation.
[x].options.time.end integer
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the [x].options.time.type property is set to absolute
  • Default = 0
The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
[x].options.time.range integer
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the [x].options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here and GCP metrics listed here.
[x].options.time.start integer
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Available if the [x].options.time.type property is set to absolute
  • Default = 0
The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
[x].options.time.type enumerated string
  • Available if the [x].options.type property is set to TimeSeriesChart
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
[x].options.timestampHidden boolean
  • Available if the [x].options.type property is set to Heatmap or SingleValue
  • Default is false
If true, the timestamp is shown below the displayed values on the chart.
[x].options.type enumerated string
  • Required
  • Supported values are: Heatmap, List, SingleValue, Text, TimeSeriesChart
The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
[x].options.unitPrefix enumerated string
  • Available if the [x].options.type property is set to anything but Text
  • Supported values are: Binary and Metric
  • Default value is Metric
Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
[x].packageSpecifications string
  • Value must be signalfx
Indicates one or more SignalFlow packages to import for use in the programText value. Currently the only the signalfx package is available.
[x].programText string
  • required for all chart types except Text
A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either colons (":") or new line characters ("\n").
[x].tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Simple Dashboard call:

Property Type Contexts Returned Description
chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All Reserved for future use
description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
discoveryOptions object All Reserved for system use.
eventOverlays list of objects All A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object All A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects All Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object All The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer All The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer All The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects All A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string All The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings All A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean All If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean All If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string All The ID of the dashboard group associated with this dashboard. A new dashboard group is created and its ID is assigned to this property as part of processing the create request.
id string All The ID assigned to the dashboard object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the dashboard cannot be modified in any way. If false, any user with access to the dashboard may edit it.
name string All The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects All A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
tags list of strings All Reserved for future use.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Dashboards

The Get Dashboards API call retrieves one or more dashboards identified by optional search criteria.

 

The Get Dashboards API call retrieves one or more dashboards identified by optional search criteria. If no search criteria is specified, the first 50 dashboards visible to the user are returned. Paging of results is controlled using the offset and limit path parameters to specify the starting point of the results and the maximum number of results to return respectively. See the path parameter documentation below for more information on search criteria and paging.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

GET https://api.signalfx.com/v2/dashboard[?[name=_dashboardName_][&][offset=_startValue_][&][limit=_requestedNumberReturned_]]

NOTE: [content] indicates that content is an optional block that may or may not be needed depending on the desired query

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Dashboards call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Query Parameters

The Get Dashboards API call supports the following query parameters as indicated in the syntax line above:

Parameter Value Type Constraints Description
limit integer
  • Default=50
  • minimum value=1
The maximum number of objects to return in the response. Unrecognized values are ignored and result in the default value of 50 being used.
name string
  • minimum characters=1
a search string acting as a full or partial match to the value in the name property of dashboard objects. Any UTF-8 characters may be included in the search string and strings will match against any portion of the name property; for example, name=per will match all of the following names:
  • ..... dropped per day...
  • ...95th percentile
  • personal disk usage...
offset integer
  • Default=0
  • minimum value=0
The starting index value of the returned objects; this assumes all of the possible returns are put in a 0-based indexed list in the appropriate sort order and identified by their order in the list. If the offset value is greater than the number of possible results, no objects are returned in the response.

Payload

The Get Dashboards API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Dashboards call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Dashboards call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Dashboards call:

Property Type Contexts Returned Description
count integer All Indicates the number of objects that match the search query. It does not provide any information on the number of objects actually returned in the request; if paging is employed the number of objects should be equivalent to either the value of the limit path parameter or the remainder of the objects after the supplied value of the offset parameter.
results list of objects All List of chart objects matching the request criteria. The properties of the included results objects are indicated as results[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the results array.
results[x].chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
results[x].charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as results[x].charts[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
results[x].charts[y].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
results[x].charts[y].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
results[x].charts[y].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
results[x].charts[y].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
results[x].charts[y].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
results[x].created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
results[x].creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].customProperties object All Reserved for future use
results[x].description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
results[x].discoveryOptions object All Reserved for system use.
results[x].eventOverlays list of objects All A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as results[x].eventOverlays[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
results[x].eventOverlays[y].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
results[x].eventOverlays[y].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as results[x].eventOverlays[y].eventSignal.propertyName in this documentation.
results[x].eventOverlays[y].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
results[x].eventOverlays[y].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
results[x].eventOverlays[y].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
results[x].eventOverlays[y].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
results[x].eventOverlays[y].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as results[x].eventOverlays[y].sources[z].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
results[x].eventOverlays[y].sources[z].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
results[x].eventOverlays[y].sources[z].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
results[x].eventOverlays[y].sources[z].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
results[x].filters object All A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as results[x].filters.propertyName in this documentation.
results[x].filters.sources list of objects All Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as results[x].filters.sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
results[x].filters.sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
results[x].filters.sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the results[x].filters.sources[x].NOT property is set to true.
results[x].filters.sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
results[x].filters.time object All The properties of the included objects are indicated as results[x].filters.time.propertyName in this documentation.
results[x].filters.time.end enumerated string or integer All The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
results[x].filters.time.start string or integer All The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
results[x].filters.variables list of objects All A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as results[x].filters.variables[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
results[x].filters.variables[y].alias string All The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
results[x].filters.variables[y].preferredSuggestions list of strings All A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If results[x].filters.variables[y].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
results[x].filters.variables[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
results[x].filters.variables[y].required boolean All If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
results[x].filters.variables[y].restricted boolean All If true, only the values set in the results[x].filters.variables[y].preferredSuggestions property are valid values for the filter criteria.
results[x].filters.variables[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
results[x].groupId string All The ID of the dashboard group associated with this dashboard.
results[x].id string All The ID assigned to the dashboard object. This ID is unique and always set by the system.
results[x].lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
results[x].lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].locked boolean All If true, the dashboard cannot be modified in any way. If false, any user with access to the dashboard may edit it.
results[x].name string All The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
results[x].selectedEventOverlays list of objects All A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the results[x].eventOverlay property instead. The properties of the included objects are indicated as results[x].selectedEventOverlays[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
results[x].selectedEventOverlays[y].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as results[x].selectedEventOverlays[y].eventSignal.propertyName in this documentation.
results[x].selectedEventOverlays[y].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
results[x].selectedEventOverlays[y].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
results[x].selectedEventOverlays[y].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as results[x].selectedEventOverlays[y].sources[z].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
results[x].selectedEventOverlays[y].sources[z].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay.
results[x].selectedEventOverlays[y].sources[z].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the results[x].selectedEventOverlays[y].sources[z].NOT property is set to true.
results[x].selectedEventOverlays[y].sources[z].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
results[x].tags list of strings All Reserved for future use.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Dashboard

The Get Dashboard API call retrieves a single v2 dashboard identified by its id value.

 

The Get Dashboard API call retrieves a single v2 dashboard identified by its id value.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

GET https://api.signalfx.com/v2/dashboard/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Dashboard call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Get Dashboard API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing dashboard object.

Payload

The Get Dashboard API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Dashboard call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Dashboard call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Dashboard call:

Property Type Contexts Returned Description
chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All Reserved for future use
description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
discoveryOptions object All Reserved for system use.
eventOverlays list of objects All A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object All A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects All Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object All The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer All The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer All The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects All A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string All The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings All A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean All If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean All If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string All The ID of the dashboard group associated with this dashboard.
id string All The ID assigned to the dashboard object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the dashboard cannot be modified in any way. If false, any user with access to the dashboard may edit it.
name string All The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects All A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
tags list of strings All Reserved for future use.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Update Dashboard

The Update Dashboard API call modifies an existing v2 dashboard identified by its id value.

 

The Update Dashboard API call modifies an existing v2 dashboard identified by its id value.

The Update Dashboard call is a full update; any properties not included in the update call will be removed or reset to their default state. In particular, if you are updating the dashboard to add additional charts, you must include all of the charts previously belonging to the dashboard to the update call or they will be removed.

NOTE: This also includes properties set by the system during object creation; resending the same payload used in the Create Dashboard call with modified values will fail. Properties set by the system during object creation should not be modified in Update Dashboard calls but resent as is. As such, they are not documented in the request payload section of this documentation.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

PUT https://api.signalfx.com/v2/dashboard/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Dashboard call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Update Dashboard API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing dashboard object to modify.

Payload

The following properties are supported in the request payload for the Update Dashboard call:

Property Type Constraints Description
chartDensity enumerated string
  • Supported values are: DEFAULT, LOW, HIGH, HIGHEST
  • Default value is DEFAULT
Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects None An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string
  • Required
  • Must map to a valid chart object
  • Must be unique across all dashboards
The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer
  • Required
  • Minimum value = 0
  • Maximum value = 11
A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer
  • Required
  • Minimum value = 1
  • Maximum value = 3
The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer
  • Required
  • Minimum value = 0
  • Maximum value = 99
A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer
  • Required
  • Minimum value = 1
  • Maximum value = 12
The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
Reserved for future use
description string
  • Default is empty string
A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
eventOverlays list of objects None A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean
  • Default is false
Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvent and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer
  • Default value=0
The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string None The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object None A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects
  • Must contain at least one element if specified
Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object None The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer
  • Must be an integer if filters.time.start is an integer
  • Must be a string if filters.time.start is a string
  • If integer:
    • Minimum value = 0
    • Value must be larger than value of filters.time.start
  • If string:
    • Allowed value is Now
The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer
  • Must be an integer if filters.time.end is an integer
  • Must be a string if filters.time.end is a string
  • If integer:
    • Minimum value = 0
    • Value must be smaller than value of filters.time.end
  • If string:
    • Value must start with a negative sign
    • A positive integer must follow the negative sign
    • Value must end with a units indicator. Allowed units indicators are m, h, d, w representing minutes, hours, days, and weeks respectively
The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects
  • Must contain at least one element if specified
A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string
  • Required
The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings None A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean
  • Default is false
If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean
  • Default is false
If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings
  • Must contain at least one element if specified
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string None The ID of the dashboard group associated with this dashboard.
name string
  • Required
  • Minimum characters = 1
The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects None A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvent and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Update Dashboard call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Update Dashboard call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Update Dashboard call:

Property Type Contexts Returned Description
chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
created string All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All Reserved for future use
description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
discoveryOptions object All Reserved for system use.
eventOverlays list of objects All A list of event overlays that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlay property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 21 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object All A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects All Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object All The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer All The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer All The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects All A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string All The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].preferredSuggestions list of strings All A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean All If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean All If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string All The ID of the dashboard group associated with this dashboard.
id string All The ID assigned to the dashboard object. This ID is unique and always set by the system.
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the dashboard cannot be modified in any way. If false, any user with access to the dashboard may edit it.
name string All The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects All A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlay property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string All The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings All A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
tags list of strings All Reserved for future use.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Delete Dashboard

The Delete Dashboard API call permanently deletes a single v2 dashboard identified by its id value.

 

The Delete Dashboard API call permanently deletes a single v2 dashboard identified by its id value.

Deleting a dashboard via the API does not affect the related charts in any way. Only the relationship between the charts and the dashboard is severed. Any charts on the deleted dashboard are orphaned and available to other dashboards. If you wish to delete them at the same time you delete their current dashboard you must send a Delete Chart API call for each chart.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

DELETE https://api.signalfx.com/v2/dashboard/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Delete Dashboard call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Delete Dashboard API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing dashboard object.

Payload

The Delete Dashboard API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Delete Dashboard call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Delete Dashboard call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Delete Dashboard API call does not send a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Dashboard Groups Overview

Dashboard groups are collections of dashboards with common characteristics that make it desirable to view them together or in sequence.

 

Dashboard groups are collections of dashboards with common characteristics that make it desirable to view them together or in sequence. In the web application, the names of member dashboards are listed in tabs across the top of the dashboard group view in alphabetical order, making it easy to switch between them.

Every dashboard group must contain at least one dashboard. In most cases, this is a one-to-many relationship where each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards. User default dashboard groups are an exception; they contain only the automatically generated user default dashboard associated with the same user the same user. For more information about user default dashboard groups see below and more information about user default dashboards see the relevant section of the Dashboards Overview.

When you create a new dashboard group, it automatically contains a new dashboard. Similarly, if you create a new dashboard and don't specify a dashboard group, a new dashboard group that contains the dashboard is created. Because a dashboard must belong to one and only one dashboard group, you cannot add existing dashboards to a new dashboard group when you create the group (because the dashboards already belong to an existing dashboard group). However, you can change the dashboard group of an existing dashboard to a different (existing) dashboard group, and you can add new dashboards to an existing dashboard group when you create them.

Existing dashboards can also be cloned into additional dashboard groups with or without minor modifications. Any dashboard can be cloned, including built-in dashboards and user specific dashboards. If you test or develop new dashboards in your user specific dashboard group, you could promote them to production when ready using a Clone Dashboard into Dashboard Group call. Similarly, if you want to modify a built-in dashboard to better suit your needs, you would clone it and then edit the cloned version however you wish.

Although the dashboard group ID is stored in the dashboard to ensure that one exists, the dashboard group -> dashboard relationship is officially managed by the containing dashboard group; the dashboards property of the associated dashboardgroup object is the system of record for determining which dashboards belong to which dashboard group.

When a dashboard group is deleted, the underlying dashboards are also deleted, as are any charts belonging to those dashboards. Note that this waterfall behavior is specific to dashboardgroup objects; when a dashboard object is manually deleted using Delete Dashboard the charts belonging to those dashboards are orphaned rather than deleted. For more information about dashboard behavior, see the Dashboards Overview. For more information about chart behavior, see the Charts Overview.

Dashboard groups can be assigned to specific teams in an organization. These groups are displayed on the team landing page for easy access by members. For more information about dashboard groups and teams see the SignalFx documentation on teams.

Dashboard groups created by API calls can be directly viewed in the web application using the id property of any of the dashboards belonging to the group as follows:

https://app.signalfx.com/#/dashboard/_id_

The dashboards belonging to the group will be displayed as linked tabs across the top of the page directly below the dashboard name:

Dashboard group with three dashboards

and will also appear by name in the catalog.

Types of Dashboard Groups

SignalFx supports three types of dashboard groups, corresponding to the three types of dashboards:

Built-in Dashboard Groups

Built-in dashboard groups contain built-in dashboards. These groups are not directly editable but are returned in Get Dashboard Group calls if their ID is known. They are not currently returned in Get Dashboard Groups calls with or without query terms. Built-in dashboard groups all have their creator property set to the system user ID "AAAAAAAAAAA".

In addition, these dashboard groups typically have descriptive names and descriptions.

Every organization starts with dashboard groups related to their organization and a set of dashboard groups with sample data. Additional built-in dashboard groups and their associated dashboards are added with each integration added to the organization.

User Default Dashboard Groups

Part of the new user account creation process involves setting up a new dashboard group (and associated new dashboard) for that user. This dashboard group is a place where that user can experiment, develop, and tweak dashboards before they're ready for wider use.

User default dashboard groups are created automatically when a user is invited to an organization and can be updated after creation. They are returned in both Get Dashboard Group and Get Dashboard Groups calls and can be identified as follows:

  • The name of the dashboard group is "<email address>'s Dashboard Group"
  • The description of the dashboard is "<email address>'s Dashboard Group"
  • The creator property of the dashboard is set to the associated user's ID (instead of the system user ID used for most actions taken directly by the system)
  • The user default dashboard is listed in the dashboards property
  • The teams property is an empty array

NOTE: Every user in the organization has the ability to edit every user's default dashboard group and dashboard. We strongly recommend that each user manage their own user default dashboard group and that users only modify their own user dashboard group, not those associated with other users in the organization. However, this is not enforced by the system.

Custom Dashboard Groups

All dashboard groups created via the SignalFx API are custom dashboard groups. These are the production dashboard groups used by an organization to monitor their systems.

Suggest Edits

Create Dashboard Group

The Create Dashboard Group API call creates a new v2 dashboardgroup object.

 

The Create Dashboard Group API call creates a new v2 dashboardgroup object.

Dashboard groups act as a container for one or more dashboards users might wish to view together or in sequence within the web application. Every dashboard must belong to a dashboard group. This is a one-to-many relationship; each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards.

In general, when you create a new dashboardgroup object a new associated dashboard object is also created. Alternately, the IDs of one or more existing orphaned dashboards may be provided in the dashboards array property at creation to assign those dashboards to the new group. In this case, the ID of the new dashboardgroup object will also be assigned to the groupId property of each of the specified dashboard as part of processing the Create Dashboard Group request. However, the dashboards property of the dashboardgroup object is the official system of record for the dashboard group -> dashboards relationship.

Once created, a dashboard group will appear in the web application and be individually viewable via the dashboard and dashboard group interface described in the SignalFx web application documentation here. It will also be listed by name in the dashboard group section of the catalog for the relevant organization.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

POST https://api.signalfx.com/v2/dashboardgroup

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Dashboard Group call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Dashboard Group call:

Property Type Constraints Description
dashboards list of strings None A list of valid IDs of dashboard objects belonging to this dashboard group. If no value is supplied at creation a new dashboard is created and assigned to this dashboard group.
description string
  • Default is empty string
A description of the dashboard group. Displays in the tooltip for the dashboard group on the Dashboards page in the web application.
name string
  • Required
  • Minimum characters = 1
The name of the dashboard group. This value is used to identify the dashboard group in the web application on the dashboards page and in the catalog. It also appears at the top left corner of the screen whenever a dashboard is being displayed.
teams list of strings None A list of valid IDs of team objects. This dashboard group is displayed on the team landing page for any team included in the list.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Dashboard Group call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Dashboard Group call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request setting