SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Metrics Metadata API

API for creating, retrieving, updating, and deleting metric names and MTS metadata.
NOTE:() Although you can't set custom properties or tags for a metric, you *can retrieve them for metrics and metric time series (MTS**).

Retrieve Dimensions Query

Retrieves metrics dimensions based on a query

get /dimension

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

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

Retrieves dimensions you specify with a query encoded on the endpoint URI. The query can contain one or more dimension names and, if desired, values. The result set contains the dimensions that match the criteria. Use other query parameters to control the number of results that the API actually sends to you.

query Parameters
query
string

Search criteria that selects the dimensions you want the API to return. You can search for the following:

  • Dimension names
  • Specific values of a dimension

Search criteria have the following rules:

  • To search for a dimension, regardless of its value, specify <name>:*
  • To search for specific values of a dimension, specify the name and value as <name>:<value>. If <value> contains non-alphanumeric characters (for example, blanks), surround it with double quotes.
  • To search for names or values using wildcards, use * as the wildcard character. For example, to search for all values of the region dimension, use region:*.
  • You can do range searches on dimensions using the syntax <name>:[<lower> to <upper>] (The value of <lower> must be less than or equal to <upper>). This works for numeric and alphabetic values.
  • To search for the existence of dimensions, use _exists_ and _missing_. For example, to search for metadata that has the host_machine dimension, specify _exists_:host_machine.
  • A single dimension name or name-value pair (or wildcards) make up a predicate that implicitly returns a boolean.
  • Join predicates with the NOT, AND, and OR boolean operators.
  • Use parentheses '(' and ')' to change the evaluation order. For example, to retrieve all metadata that has the dimensions region:emea and hostname:"france-*"", usequery="region:emea AND hostname:"france-*"`.
orderBy
string

The metadata property on which the API should sort the results. You don't have to include this property in the query, but the name must be metadata for a metric.

offset
integer <int32>

The result object in the result set at which the API should start returning results to you. If omitted, the API starts at the first result in the set.

limit
integer <int32>

The number of results to return from the result set.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful metric retrieval

Response Schema: application/json
count
integer

The number of objects the API returned. This is the same as the size of the results property array.

results
Array of objects (DimensionQueryResponseObject)

An array of JSON objects (dictionaries). Each object contains metadata for one dimension that matched the query.

Response samples

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

Retrieve Dimension Metadata Name Value

Retrieves metadata for a dimension and value

get /dimension/{key}/{value}

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

https://api.{realm}.signalfx.com/v2/dimension/{key}/{value}

Retrieves the metadata for the dimension and value specified in the path parameters

path Parameters
key
required
string

A dimension name (key) for an existing dimension

value
required
string

A dimension value for an existing dimension

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of metadata for a dimension and value

Response Schema: application/json
created
integer <int64>

Creation timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was first created * For a PUT request: timestamp to set as the creation time; the response echoes the request value.

creator
string

A SignalFx user ID:

  • For a GET request: The user that created the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
customProperties
object <= 50 items

The custom properties for the dimension, in the form of a JSON object (dictionary) containing custom property key-value pairs:

  • For a GET response, this value contains the existing custom properties.
  • For a PUT request, use this property to update custom properties for the dimension. The PUT response returns all of the custom properties for the specified dimension. The section Custom Properties Criteria lists the requirements for custom properties.
description
string <UTF-8> [ 0 .. 1024 ] characters

The description for the dimension. You can use up to 1024 UTF-8 characters.

key
string <= 128 characters

A dimension name (key) for an existing dimension:

  • For a GET response, this value is the dimension name retrieved by the request.
  • For a PUT request, this value is the dimension you want to update. The PUT response echoes the request body. The section Dimension Criteria lists the requirements for dimensions.
lastUpdated
integer <int64>

Last updated timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was updated * For a PUT request: timestamp to set as the update time; the response echoes the request value.

lastUpdatedBy
string

A SignalFx user ID:

  • For a GET request: The user that last updated the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
tags
Array of strings <= 50 items

The tags for the dimension:

  • For a GET response, this value contains the tags.
  • For a PUT request, use this property to update tags for the dimension. The PUT response returns all of the tags for the specified dimension. The section Tags Criteria lists the requirements for tags.
value
string <= 256 characters

A dimension value for an existing dimension.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1557484230100,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "lastUpdated": 1557570630000,
  • "lastUpdatedBy": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Update Dimension Metadata

Updates dimension metadata for the dimension specified by the key

put /dimension/{key}/{value}

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

https://api.{realm}.signalfx.com/v2/dimension/{key}/{value}

Overwrites the metadata for the dimension and value specified in the path parameters

path Parameters
key
required
string

The dimension name (key) for the dimension you want to update

value
required
string

The dimension value for the dimension you want to update

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Request Body schema: application/json

Custom properties or tags (or both) that you want to add or update for the dimension

created
integer <int64>

Creation timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was first created * For a PUT request: timestamp to set as the creation time; the response echoes the request value.

creator
string

A SignalFx user ID:

  • For a GET request: The user that created the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
customProperties
object <= 50 items

The custom properties for the dimension, in the form of a JSON object (dictionary) containing custom property key-value pairs:

  • For a GET response, this value contains the existing custom properties.
  • For a PUT request, use this property to update custom properties for the dimension. The PUT response returns all of the custom properties for the specified dimension. The section Custom Properties Criteria lists the requirements for custom properties.
description
string <UTF-8> [ 0 .. 1024 ] characters

The description for the dimension. You can use up to 1024 UTF-8 characters.

key
string <= 128 characters

A dimension name (key) for an existing dimension:

  • For a GET response, this value is the dimension name retrieved by the request.
  • For a PUT request, this value is the dimension you want to update. The PUT response echoes the request body. The section Dimension Criteria lists the requirements for dimensions.
lastUpdated
integer <int64>

Last updated timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was updated * For a PUT request: timestamp to set as the update time; the response echoes the request value.

lastUpdatedBy
string

A SignalFx user ID:

  • For a GET request: The user that last updated the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
tags
Array of strings <= 50 items

The tags for the dimension:

  • For a GET response, this value contains the tags.
  • For a PUT request, use this property to update tags for the dimension. The PUT response returns all of the tags for the specified dimension. The section Tags Criteria lists the requirements for tags.
value
string <= 256 characters

A dimension value for an existing dimension.

Responses

200

Successful overwrite of metadata for the specified dimension and value

Response Schema: application/json
created
integer <int64>

Creation timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was first created * For a PUT request: timestamp to set as the creation time; the response echoes the request value.

creator
string

A SignalFx user ID:

  • For a GET request: The user that created the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
customProperties
object <= 50 items

The custom properties for the dimension, in the form of a JSON object (dictionary) containing custom property key-value pairs:

  • For a GET response, this value contains the existing custom properties.
  • For a PUT request, use this property to update custom properties for the dimension. The PUT response returns all of the custom properties for the specified dimension. The section Custom Properties Criteria lists the requirements for custom properties.
description
string <UTF-8> [ 0 .. 1024 ] characters

The description for the dimension. You can use up to 1024 UTF-8 characters.

key
string <= 128 characters

A dimension name (key) for an existing dimension:

  • For a GET response, this value is the dimension name retrieved by the request.
  • For a PUT request, this value is the dimension you want to update. The PUT response echoes the request body. The section Dimension Criteria lists the requirements for dimensions.
lastUpdated
integer <int64>

Last updated timestamp, in Unix time UTC-relative:
* For a GET request: time when the dimension was updated * For a PUT request: timestamp to set as the update time; the response echoes the request value.

lastUpdatedBy
string

A SignalFx user ID:

  • For a GET request: The user that last updated the dimension.
  • For a PUT request, the ID of the user that's making the request; the response echoes the request value.
tags
Array of strings <= 50 items

The tags for the dimension:

  • For a GET response, this value contains the tags.
  • For a PUT request, use this property to update tags for the dimension. The PUT response returns all of the tags for the specified dimension. The section Tags Criteria lists the requirements for tags.
value
string <= 256 characters

A dimension value for an existing dimension.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1557484230100,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "lastUpdated": 1557570630000,
  • "lastUpdatedBy": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1557484230100,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "lastUpdated": 1557570630000,
  • "lastUpdatedBy": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Retrieve Metrics Metadata Using Query

Retrieves metrics metadata based on a query

get /metric

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

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

Retrieves metadata for metrics based on the following possible search criteria, specified in the query parameter:

  • Metric name
  • Dimension name and, if desired, value
  • Property name and, if desired, value
  • Tag
    The result contains all of the metrics that match the criteria. Use other query parameters to control the number of results that the API actually sends to you.
query Parameters
query
string

Search criteria that selects the metrics metadata you want the API to return. You can search for the following:

  • Metric names that have the metadata you want
  • Dimension names associated with the metadata
  • Values of a dimension associated with the metadata
  • Custom property metadata
  • Values of custom property metadata
  • Tag metadata
    Search criteria have the following rules:
  • To search for a metric, specify <metric_name>. The result is all the metadata associated with that metric.
  • To search for metadata, regardless of its value, specify <metadata_name>:*.
  • To search for specific values of metadata, specify the name and value as <metadata_name>:<value>. If <value> contains non-alphanumeric characters (for example, blanks), surround it with double quotes.
  • To search for names or values using wildcards, use * as the wildcard character. For example, to search for all values of the region dimension, use region:*.
  • You can do range searches on metrics, dimensions or properties using the syntax <name>:[<lower> to <upper>] (The value of <lower> must be less than or equal to <upper>). This works for numeric and alphabetic values.
  • To search for the existence of dimensions or properties, use _exists_ and _missing_. For example, to search for metadata that has the host_machine dimension, specify _exists_:host_machine.
  • A single property name and value (or wildcards) make up a predicate that implicitly returns a boolean.
  • Join predicates with the NOT, AND, and OR boolean operators.
  • Use parentheses '(' and ')' to change the evaluation order. For example, to retrieve all metadata that has the dimension region:emea and the custom property company with values that start with Schneider*, use query="region:emea AND company:Schneider*.
orderBy
string

The metadata property on which the API should sort the results. You don't have to include this property in the query, but the name must be metadata for a metric.

offset
integer <int32>

The result object in the result set at which the API should start returning results to you. If omitted, the API starts at the first result in the set.

limit
integer <int32>

The number of results to return from the result set.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful metrics metadata retrieval request

Response Schema: application/json
count
integer

Number of result objects returned. This value is the same as the size of the result value array.

result
Array of objects (RetrieveMetricMetadataResponseObject)

An array of metrics metadata results

Response samples

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

Retrieve Metrics Metadata Metric Name

Retrieves the metrics metadata for a metric name

get /metric/{name}

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

https://api.{realm}.signalfx.com/v2/metric/{name}

Retrieves the metrics metadata for the metric name specified in the {name} path parameter. The API returns all of the metadata for this metric.

path Parameters
name
required
string
Example: "network.usage.rx_bytes"

Name of an existing metric. For example, to retrieve the metadata for the cpu.utilization metric, use the endpoint https://api.{REALM}.signalfx.com/v2/metric/cpu.utilization

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of metrics metadata for a specified metric.

Response Schema: application/json
created
integer <int64>

The time that the metric was created, in Unix time UTC-relative

creator
string

SignalFx ID of the user who created the metric. If the value is "AAAAAAAAAAA", SignalFx created the metric.

customProperties
object <= 50 items

Custom property metadata for the result object, in the form of a JSON object (dictionary). Each property is a custom property name and value. Custom property names and values have these requirements
Name:

  • UTF-8 string, maximum length of 128 characters (512 bytes)
  • Must start with an uppercase or lowercase letter. The rest of the name can contain letters, numbers, underscores (_) and hyphens (-).
  • Must not start with the underscore character (_)


Value:

  • String: Maximum length 256 UTF-8 characters (1024 bytes)
  • Integer or float: Maximum length 8192 bits (1024 bytes)
description
string <UTF-8> [ 0 .. 1024 ] characters

Description of the metric that has the retrieved metadata. You can use up to 1024 UTF-8 characters.

dimensions
object <= 50 items

Dimension metadata for the result object, in the form of a JSON object (dictionary). Each property is a dimension name and dimension value. Dimension names and values have these requirements:
Name:

  • UTF-8 string, maximum length of 128 characters (512 bytes)
  • Must start with an uppercase or lowercase letter. The rest of the name can contain letters, numbers, underscores (_) and hyphens (-).
  • Must not start with the underscore character (_)
  • Must not start with the prefix sf_, except for dimensions defined by SignalFx such as sf_hires
  • Must not start with the prefix aws_


Value:

  • String: Maximum length 256 UTF-8 characters (1024 bytes)
  • Integer or float: Maximum length 8192 bits (1024 bytes)
lastUpdated
integer <int64>

The time that the metric was last updated, in Unix time UTC-relative

lastUpdatedBy
string

SignalFx ID of the user who last updated the metric. If the value is "AAAAAAAAAAA", SignalFx last updated the metric.

name
string

Name of the metric that has the retrieved metadata

tags
Array of strings <= 50 items

Tag metadata in the response, in the form of a JSON array (a list) with one element for each tag. Each tag is a UTF-8 string, starting with an uppercase or lowercase alphabetic character. The maximum length is expressed in characters; if a string consists solely of single-byte UTF-8 entities, 1024 characters are available.

type
string
Enum:"GAUGE" "COUNTER" "CUMULATIVE_COUNTER"

Metric type of the metric that has the retrieved metadata. The possible values are "GAUGE", "COUNTER", and "CUMULATIVE_COUNTER".

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556055030000,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "dimensions": { },
  • "lastUpdated": 1556141430000,
  • "lastUpdatedBy": "string",
  • "name": "string",
  • "tags":
    [
    ],
  • "type": "GAUGE"
}

Retrieve Metric Timeseries Metadata

Retrieves metric timeseries (MTS) metadata based on a query

get /metrictimeseries

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

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

Retrieves all the metadata for the metric timeseries that match the search criteria specified in the query parameter. You can search on metric name, dimension name or value or both, custom property name or value or both, and tag name.

query Parameters
query
string

Search criteria that selects the metrics metadata you want the API to return. You can search for the following:

  • Metric names
  • Dimension names
  • Values of a dimension
  • Custom properties
  • Values of a custom property
  • Tags
    Search criteria have the following rules:
  • To search for a metric, specify its name. The result is all the metadata associated with that metric.
  • To search for metadata that has a dimension or property, regardless of the value, specify <name>:*
  • To search for specific values of a dimension or property, specify the name and value as <name>:<value>. If <value> contains non-alphanumeric characters (for example, blanks), surround it with double quotes.
  • To search for names or values using wildcards, use * as the wildcard character. For example, to search for all values of the region dimension, use region:*.
  • You can do range searches on metrics, dimensions or properties using the syntax <name>:[<lower> to <upper>] (The value of <lower> must be less than or equal to <upper>). This works for numeric and alphabetic values.
  • To search for the existence of dimensions or properties, use _exists_ and _missing_. For example, to search for metadata that has the host_machine dimension, specify _exists_:host_machine.
  • A single name and value (or wildcards) make up a predicate that implicitly returns a boolean.
  • Join predicates with the NOT, AND, and OR boolean operators.
  • Use parentheses '(' and ')' to change the evaluation order. For example, to retrieve all metadata that has the dimension region:emea and the custom property company with values that start with Schneider*, use query="region:emea AND company:Schneider*.
orderBy
string

The metadata property on which the API should sort the results. You don't have to include this property in the query, but the name must be metadata for a metric.

offset
integer <int32>

The position of a result object that contains metadata for a single match within the entire set of results of the query. The API starts returning results at this point. If omitted, the API starts at the first result in the set.

limit
integer <int32>

The number of result objects to return from the result set.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful MTS retrieval request

Response Schema: application/json
count
integer

The number of objects the API returned. This is the same as the size of the results property array.

results
Array of objects (MTSRetrieveResponseObject)

An array of JSON objects (dictionaries). Each object contains the metadata for one MTS that matched the query.

Response samples

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

Retrieve MTS Metadata ID

Retrieves the MTS metadata for a metric timeseries

get /metrictimeseries/{id}

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

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

Retrieves all the metadata for the single metric timeseries specified by the {id} path parameter.

path Parameters
id
required
string

The SignalFx-assigned ID of the metric timeseries for which you want to retrieve metadata.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of the specified MTS

Response Schema: application/json
created
integer <int64>

The time that the MTS was created, in Unix time UTC-relative

creator
string

SignalFx ID of the user who created the MTS. If the value is "AAAAAAAAAAA", SignalFx created the MTS.

customProperties
object <= 50 items

Custom property metadata for the MTS, in the form of a JSON object (dictionary). Each property is a custom property name and value. The section Custom Properties Criteria lists the requirements for custom properties. Custom property metadata for the MTS, in the form of a JSON object (dictionary). Each property is a custom property name and value. Custom property names and values have these criteria:
Name:

  • UTF-8 string, maximum length of 128 characters (512 bytes)
  • Must start with an uppercase or lowercase letter. The rest of the name can contain letters, numbers, underscores (_) and hyphens (-).
  • Must not start with the underscore character (_)


Value:

  • String: Maximum length 256 UTF-8 characters (1024 bytes)
  • Integer or float: Maximum length 8192 bits (1024 bytes)
dimensions
object <= 50 items

Dimension metadata for the MTS, in the form of a JSON object (dictionary). Each property is a dimension name and dimension value. The section Dimension Criteria lists the requirements for dimensions.

lastUpdated
integer <int64>

The time that the MTS was last updated, in Unix time UTC-relative

lastUpdatedBy
string

SignalFx ID of the user who last updated the MTS. If the value is "AAAAAAAAAAA", SignalFx last updated the metric.

metric
string <= 256 characters

Name of the MTS. Metric names are UTF-8 strings with a maximum length of 256 characters (1024 bytes).

tags
Array of strings <= 50 items

Tag metadata for the MTS, in the form of a JSON array (a list) with one element for each tag.
Each tag is a UTF-8 string, starting with an uppercase or lowercase alphabetic character. The maximum length is expressed in characters; if a string consists solely of single-byte UTF-8 entities, 1024 characters are available.

type
string
Enum:"GAUGE" "COUNTER" "CUMULATIVE_COUNTER"

Metric type of the MTS for this metadata. The possible values are "GAUGE", "COUNTER", and "CUMULATIVE_COUNTER".

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1557743430000,
  • "creator": "string",
  • "customProperties": { },
  • "dimensions": { },
  • "lastUpdated": 1557916230000,
  • "lastUpdatedBy": "string",
  • "metric": "string",
  • "tags":
    [
    ],
  • "type": "GAUGE"
}

Retrieve Tag Metadata Query

Retrieves a tag and its metadata, based on a query

get /tag

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

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

Retrieves a tag and its metadata, based on a query that specifies search criteria. The result contains all of the tags that match the criteria. Use other query parameters to control the number of results that the API actually sends to you.

query Parameters
query
string

Search criteria that selects the tags you want the API to return
The search criteria have the following rules:

  • To search for a tag, specify its name.
  • To search for tags using wildcards, use * to match multiple characters or ? to match a single character. For example, to search for tags that start with the string "python", use `query="python*".
orderBy
string

The metadata property on which the API should sort the results. You don't have to include this property in the query, but the name must be metadata for a metric.

offset
integer <int32>

The object in the result set at which the API should start returning results to you. Each object contains the metadata for a tag that matches the search criteria.

limit
integer <int32>

The number of results to return from the result set.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of the metadata for tags specified by search criteria

Response Schema: application/json
count
integer

The number of objects the API returned. This is the same as the size of the results property array.

results
Array of objects (TagRetrieveResponseObject)

An array of JSON objects (dictionaries). Each object contains the metadata for one tag that matched the query.

Response samples

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

Delete Single Tag

Deletes the tag specified in the {name} path parameter

delete /tag/{name}

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

https://api.{realm}.signalfx.com/v2/tag/{name}

Deletes the tag specified in the {name} path parameter

path Parameters
name
required
string

The tag you want to delete

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful tag deletion

404

Unable to find the specified tag

Retrieve Tag Metadata Name

Retrieves metadata for a tag

get /tag/{name}

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

https://api.{realm}.signalfx.com/v2/tag/{name}

Retrieves the tag metadata for the tag specified in the {name} path parameter. The metadata includes any custom properties defined for the tag.

path Parameters
name
required
string

The tag you want to retrieve

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of tag metadata for a specified tag

Response Schema: application/json
created
integer <int64>

The time that the tag was created, in Unix time UTC-relative.

creator
string

SignalFx ID of the user who created the tag. If the value is "AAAAAAAAAAA", SignalFx created the tag.

customProperties
object

The custom properties for the tag, in the form of a JSON object (dictionary). Each property is a custom property name and value. The section Custom Properties Criteria lists the requirements for custom property names and values.

description
string <UTF-8> [ 0 .. 1024 ] characters

A description of the tag. You can use up to 1024 UTF-8 characters.

lastUpdated
integer <int64>

The time that the tag was last updated, in Unix time UTC-relative

lastUpdatedBy
string

SignalFx ID of the user who last updated the tag. If the value is "AAAAAAAAAAA", SignalFx last updated the metric.

name
string <UTF-8> <= 256 characters

The tag. Tags are in UTF-8 format. The section Tags Criteria lists the requirements for tags.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1554287430000,
  • "creator": "string",
  • "customProperties":
    {
    },
  • "description": "string",
  • "lastUpdated": 1555497030000,
  • "lastUpdatedBy": "string",
  • "name": "string"
}

Create Update Tag

Creates or updates a tag

put /tag/{name}

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

https://api.{realm}.signalfx.com/v2/tag/{name}

Creates or updates a tag specified in the {name} path parameter.

path Parameters
name
required
string

The tag you want to create or update. The section Tags Criteria lists the requirements for tags.

header Parameters
Content-Type
required
string

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

X-SF-TOKEN
required
string

Authentication token.

Request Body schema: application/json

Metadata for the tag you're creating or updating. The request body is optional.

customProperties
object <= 50 items

The custom properties for the tag, in the form of a JSON object (dictionary). Each property is a custom property name and value. The section Custom Properties Criteria lists the requirements for custom property names and values.

description
string <UTF-8> [ 0 .. 1024 ] characters

Description of the tag you're adding or updating. You can use up to 1024 UTF-8 characters.

Responses

200

Successful tag creation or update

Response Schema: application/json
created
integer <int64>

The time that the tag was created, in Unix time UTC-relative.

creator
string

SignalFx ID of the user who created the tag. If the value is "AAAAAAAAAAA", SignalFx created the tag.

customProperties
object

The custom properties for the tag, in the form of a JSON object (dictionary). Each property is a custom property name and value. The section Custom Properties Criteria lists the requirements for custom property names and values.

description
string <UTF-8> [ 0 .. 1024 ] characters

A description of the tag. You can use up to 1024 UTF-8 characters.

lastUpdated
integer <int64>

The time that the tag was last updated, in Unix time UTC-relative

lastUpdatedBy
string

SignalFx ID of the user who last updated the tag. If the value is "AAAAAAAAAAA", SignalFx last updated the metric.

name
string <UTF-8> <= 256 characters

The tag. Tags are in UTF-8 format. The section Tags Criteria lists the requirements for tags.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customProperties": { },
  • "description": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1554287430000,
  • "creator": "string",
  • "customProperties":
    {
    },
  • "description": "string",
  • "lastUpdated": 1555497030000,
  • "lastUpdatedBy": "string",
  • "name": "string"
}