Entities: list

Description

Retrieves a list of entities matching the specified filters.

Request

Method Path
GET /api/v1/entities

Query Parameters

Name Type Description
expression string Include entities that match a filter expression consisting of fields and operators. Supported wildcards: * and ?.
minInsertDate string Include entities with lastInsertDate equal or greater than minInsertDate.
The parameter can be specified in ISO 8601 format or using calendar keywords.
maxInsertDate string Include entities with lastInsertDate less than maxInsertDate, including metrics without lastInsertDate.
The parameter can be specified in ISO format or using calendar keywords.
limit integer Maximum number of entities to retrieve, ordered by name.
tags string Comma-separated list of entity tag names to include in the response, for example, tags=OS,location.
Specify tags=* to include all entity tags.
Specify tags=env.* to include all entity tags starting with env..
addInsertTime boolean Controls whether lastInsertDate field is included in the response.
The default value is inherited from the default.addInsertTime setting on the Settings > Server Properties page which is set to true by default.

Expression

The expression can include all fields listed below except lastInsertDate.

Examples:

name LIKE 'nur*'

name NOT LIKE 'aws*' AND lower(label) NOT LIKE 'aws*' AND createdDate > '2017-10-01T00:00:00Z'

name LIKE '*db*' AND lower(tags.function) = 'database'

The lastInsertDate field can be filtered using minInsertDate and maxInsertDate parameters for performance reasons.

Response

Fields

Name Type Description
name string Entity name.
label string Entity label.
enabled boolean Enabled status. Incoming data is discarded for disabled entities.
interpolate string Interpolation mode: LINEAR or PREVIOUS.
Used in SQL WITH INTERPOLATE clause when interpolation mode is set to AUTO, for example, WITH INTERPOLATE(1 MINUTE, AUTO).
timeZone string Time Zone ID, for example EST.
Refer to the Time Zone table for a list of supported Time Zone IDs.
The time zone is applied by date-formatting functions to return local time in entity-specific time zone.
createdDate string Date of entity creation in ISO 8601 format.
lastInsertDate string Last time a value is received by the database for this entity in ISO format.
tags object Entity tags, as requested with the tags parameter.

Interpolate

Type
LINEAR
PREVIOUS

Example 1

Request

URI

GET /api/v1/entities?timeFormat=iso&limit=2&expression=name%20LIKE%20%27nurs*%27

Payload

None.

curl

curl "https://atsd_hostname:8443/api/v1/entities?timeFormat=iso&limit=2&expression=name%20LIKE%20%27nurs*%27" \
  --insecure --include --user {username}:{password}

Response

[
  {
    "name": "nurswgdkr002",
    "enabled": true,
    "lastInsertDate": "2015-09-04T15:43:36.000Z",
    "createdDate": "2014-10-03T07:09:54.551Z"
  },
  {
    "name": "nurswgvml001",
    "label": "NURSWGDKR002.corp.example.org",
    "enabled": false
  }
]

Example 2

Expression value:

name!="" or tags.keyName!="" or label!=null or enabled=true or interpolate="LINEAR" or timeZone!=""

Request

URI

GET /api/v1/entities?expression=label!=%22%22%20and%20enabled=true%20and%20interpolate!=%22%22%20and%20timeZone!=%22%22

Payload

None.

curl

curl https://atsd_hostname:8443/api/v1/entities?expression=label!=%22%22%20and%20enabled=true%20and%20interpolate!=%22%22%20and%20timeZone!=%22%22 \
  --insecure --include --user {username}:{password}

Response

[
  {
    "name": "nurswgdkl001",
    "enabled": true,
    "timeZone": "PST",
    "lastInsertDate": "2016-10-28T08:37:05.000Z",
    "interpolate": "LINEAR",
    "label": "NURswgdkl001"
  }
]

Additional examples