Query Syntax

Intersight provides a rich query language based on the OData standard. The query language is represented using URL query parameters for GET requests. The query component is indicated by the first question mark ("?") character and terminated by a number sign ("#") character or by the end of the URL.

In all query examples below, the URL scheme and host name have been omitted for simplicity. The full query URL should include https://intersight.com/.

Supported Types

String

A string is a sequence of characters enclosed within single-quotes. Strings are represented in UTF-8 format and support Unicode characters.

Number

A numeric value may be a signed or unsigned integer, or a floating number. Numeric values are specified without quotes.

Date and Time

A Date/Time represents an instant in time with millisecond precision. The date/time syntax uses the "date-time" notation which is specified in RFC 3339. It is expressed in coordinated Universal Time (UTC) without quotes: YYYY-mm-ddTHH:MM:ssZ

For example: 2018-06-20T05:31:38.862Z

Time of day

The time of day, expressed in hours, minutes, seconds and fractional seconds, with millisecond precision. The Time of day syntax uses the "partial-time" notation which is specified in RFC 3339.

For example: 05:31:38.862

Duration

A duration represents the elapsed time between two instants. For example, "15 days" and "2 hours, 20 minutes" are duration values.

Intersight uses the ODATA and ISO 8601 syntax to represent durations. When present in a URL, a duration value is a quoted string that contains a sequence of fragments for years, months, days, hours, minutes and fractional seconds. Supported units are year ('Y'), month ('M'), day ('D'), hour ('H'), minute ('M') and seconds ('S'). Sub-second duration may be represented with a period and decimal value.

The duration value must start with the character 'P'.
Each fragment is an integer followed by a single letter representing the unit.
The year, month and day are written immediately after the 'P'.
When hours, minutes or seconds are specified, they must be preceded by the letter 'T'.

Examples:

Syntax	Description
P1Y	1 year
P3M	3 months
P20D	20 days
P1DT2H	1 day and 2 hours
PT60H	60 hours
PT20M	20 minutes
PT5S	5 seconds
PT5.123	5 seconds and 123 milliseconds
P1DT2H20M10S	1 day, 2 hours, 20 minutes and 10 seconds

Parenthesis: specifying operator precedence

The Grouping operators controls the evaluation order of an expression. The syntax for grouping are open and close parenthesis. The Grouping operator returns the expression grouped inside the parenthesis.

Example: Query RackUnit resources where the model property is not ('HX220C-M5SX' or 'HX220C-M5S').

GET /api/v1/compute/RackUnits?$select=Vendor,Model,Serial&$top=10&$filter=not(Model eq 'HX220C-M5SX' or Model eq 'HX220C-M5S')

Referencing Properties By Name

URL ODATA query parameters may include expressions that refer to named properties in the JSON representation of the REST resources. The expressions may be used to filter, select, count, sort, aggregate, expand or search, and may refer to top-level or nested properties. For example, consider the following REST resource:

{
  "Moid": "59696c6ca94c04000137e67a",
  "ObjectType": "adapter.Unit",
  "CreateTime": "2017-07-15T01:14:20.742Z",
  "ModTime": "2018-05-02T01:36:19.872Z",
  "Model": "UCSB-VIC-M83-8P",
  "Serial": "FCH18207DCK",
  "Parent": {
    "ObjectType": "compute.Blade",
    "Moid": "59696c7ba94c04000137e818",
    "link": "https://intersight.com/api/v1/compute/Blades/59696c7ba94c04000137e818"
  },
  ...
}

The above representation includes top-level properties such as "Model", "Serial", and nested properties such as "Parent/ObjectType". Nested properties are identified by concatenating the name of the properties separed with the '/' character.

$filter Query Option: Filtering the Resources

The $filter query option allows clients to filter resources based on some expression and retrieve a subset of resources. The $filter option supports multiple operators to filter managed objects.

Logical Operators

"Equal" Operator

The eq operator returns true if the left operand is equal to the right operand, otherwise it returns false. The eq operator accepts numeric, dates and string values.

Example: Query RackUnit resources where Serial equals to "WZP211704KM"

GET /api/v1/compute/RackUnits?$filter=Name eq 'WZP211704KM'

Example: Query RackUnit resources where the value of the 'Model' property is equal to 'UCSC-C240-M5SN'

GET /api/v1/compute/RackUnits?$filter=Model eq 'UCSC-C240-M5SN'

Example: Query RackUnit resources where the number of CPU cores is 24. Numeric values are specified without quotes.

GET /api/v1/compute/RackUnits?$filter=NumCpuCores eq 24

Example: Query Audit log records where 'CreationTime' is '2018-06-20T05:31:38.862Z'.

GET /api/v1/aaa/AuditRecords?$filter=CreateTime eq 2018-06-20T05:31:38.862Z

"Not Equal" Operator

The ne operator returns true if the left operand is not equal to the right operand, otherwise it returns false. The ne operator accepts numeric, dates and string values.

Example: Query RackUnit resources where Serial is not equal to "WZP211704KM"

GET /api/v1/compute/RackUnits?$filter=Name ne 'WZP211704KM'

Example: Query RackUnit resources where the value of the 'Model' property is not equal to 'UCSC-C240-M5SN'

GET /api/v1/compute/RackUnits?$filter=Model ne 'UCSC-C240-M5SN'

"Greater Than" Operator

The gt operator returns true if the left operand is greater than the right operand, otherwise it returns false. The gt operator accepts numeric, dates and string values

Example: Query RackUnit resources where AvailableMemory is greater than 98304MB:

GET /api/v1/compute/RackUnits?$filter=AvailableMemory gt 98304

Example: Query Audit log records where 'CreationTime' is greater than '2018-06-20T05:31:38.862Z'. The date must be specified in UTC time without quotes.

GET /api/v1/aaa/AuditRecords?$filter=CreateTime gt 2018-06-20T05:31:38.862Z

"Less Than" Operator

The lt operator returns true if the left operand is less than the right operand, otherwise it returns false. The lt operator accepts numeric, dates and string values

Example: Query RackUnit resources where AvailableMemory is less than 98304MB:

GET /api/v1/compute/RackUnits?$filter=AvailableMemory lt 98304

"Greater Than Or Equal" Operator

The ge operator returns true if the left operand is greater than or equal to the right operand, otherwise it returns false. The ge operator accepts numeric, dates and string values

Example: Query RackUnit resources where AvailableMemory is greater than or equal to 98304MB:

GET /api/v1/compute/RackUnits?$filter=AvailableMemory gt 98304

"Less Than Or Equal" Operator

The le operator returns true if the left operand is less than or equal to the right operand, otherwise it returns false. The le operator accepts numeric, dates and string values

Example: Query RackUnit resources where AvailableMemory is less than or equal to 98304MB:

GET /api/v1/compute/RackUnits?$filter=AvailableMemory le 98304

"And" Operator

The and operator returns true if both the left and right operands evaluate to true, otherwise it returns false.

Example: Query RackUnit resources where the Model property is equal to 'UCSC-C240-M5SN'and the server has more than 64GB of memory:

GET /api/v1/compute/RackUnits?$filter=Model eq 'UCSC-C240-M5SN' and AvailableMemory gt 65000

"Or" Operator

The or operator returns true if either the left or right operand evaluate to true, otherwise it returns false.

Example: Query RackUnit resources where the Model property is equal to 'UCSC-C240-M5SN' or the Model property is equal to 'UCSC-C240-M5SN'. Use the $select keyword to reduce the size of the output JSON document.

"Not" Operator

The not operator returns true if the operand returns false, otherwise it returns false.

Example: Query RackUnit resources where the model property is not ('HX220C-M5SX' or 'HX220C-M5S'). The example shows how grouping parenthesis can be used to set the operator precedence.

GET /api/v1/compute/RackUnits?$select=Vendor,Model,Serial&$top=10&$filter=not(Model eq 'HX220C-M5SX' or Model eq 'HX220C-M5S')

"In" Operator

The in operator returns true if the left operand is equal to one of the values specified in the right operand, otherwise it returns false. The in operator accepts numeric and string values.

Values must be specified as a comma-separated list enclosed in parenthesis.

Example: Query RackUnit resources where Model is either 'HX220C-M5SX' or 'UCSC-C240-M5SN'.

GET /api/v1/compute/RackUnits?$filter=Model in ('HX220C-M5SX', 'UCSC-C240-M5SN')

String Functions

"contains" Function

The contains function has the following signature:

boolean contains(s string, subst string)

The contains function returns true if the second parameter string value is a substring of the first parameter string value, otherwise it returns false.

Example: Query RackUnit resources where the value of the 'Model' property contains 'C240'

GET /api/v1/RackUnits?$filter=contains(Model,'C240')

"startsWith" Function

The startswith function has the following signature:

boolean startswith(s string, subst string)

The startswith function returns true if the first parameter string value starts with the second parameter string value, otherwise it returns false.

Example: Query RackUnit resources where the value of the 'Model' property starts with the prefix 'UCSC‑C240'

GET /api/v1/RackUnits?$filter=startswith(Model,'UCSC-C240')

"endswith" Function

The endswith function has the following signature:

boolean endswith(string, suffix string)

The endswith function returns true if the first parameter string value ends with the second parameter string value, otherwise it returns false.

Example: Query RackUnit resources where the value of the 'Model' property ends with the suffix 'M5'

GET /api/v1/RackUnits?$filter=endswith(Model,'M5')

"tolower" Function

The tolower function has the following signature:

string tolower(string)

The tolower function returns the input parameter string value with all uppercase characters converted to lowercase according to Unicode rules.

"toupper" Function

The toupper function has the following signature:

string toupper(string)

The toupper function returns the input parameter string value with all lowercase characters converted to uppercase according to Unicode rules.

Lambda Operators

Lambda operators filter managed objects by executing a function against one or more items in a list, such as a list of tags in a managed object.

Lambda "any" Operator

The any operator applies a Boolean expression to each member of a collection. The members of the collection may be nested objects or primitive types such as strings. The any operator returns true if the expression is true for at least one member of the collection, otherwise it returns false.

The any operator must be prepended with a navigation path that identifies the collection. The argument of a lambda operator is a lambda variable name followed by a colon (:) and a Boolean expression that uses the lambda variable name to refer to properties of the related entities identified by the navigation path.

For example, consider the RackUnits resource. It has the following properties:

The Tags property is a collection of Key/Value pairs, which are represented in JSON format as an array of nested objects.
The Owners property is a collection of string values (primitive type).

{
  "Moid": "58e6de34e138234f057fe8cd",
  "CreateTime": "2017-04-06T17:32:52.965-07:00",
  "ModTime": "2017-04-06T17:32:52.975-07:00",
  "Owners": [
    "58e6de34e138234f057fe800",
    "58e6de34e138234f057fe801"
  ],
  "Tags": [
    {
      "Key": "Site",
      "Value": "Paris"
    },
    {
      "Key": "Application",
      "Value": "database"
    },
    {
      "Key": "Environment",
      "Value": "Production"
    }
  ]
}

An API client can filter the RackUnits API based on the content of the Owners and/or Tags collections.

Example 1: Query the RackUnit resources that have a tag Key set to "Site". The tag Value is ignored.

GET /api/v1/compute/RackUnits?$filter=Tags/any(t:t/Key eq 'Site')

Output

{
  "Moid": "58e6de34e138234f057fe8cd",
  "CreateTime": "2017-04-06T17:32:52.965-07:00",
  "ModTime": "2017-04-06T17:32:52.975-07:00",
  "Tags": [
    {
      "Key": "Site",
      "Value": "Paris"
    },
    {
      "Key": "Application",
      "Value": "database"
    }
  ]
}

Example 2: Query RackUnit resources that have a tag Key set to "Site" and the corresponding Tag Value is set to "London".

GET /api/v1/compute/RackUnits?$filter=Tags/any(t:t/Key eq 'Site' and t/Value eq 'London')

Example 3: Query RackUnit resources that satisfy two constraints:

Site is 'London', and
Environment is 'Production'

GET /api/v1/compute/RackUnits?$filter=Tags/any(t:t/Key eq 'Site' and t/Value eq 'London') and Tags/any(t:t/Key eq 'Environment' and t/Value eq 'Production')

Output

{
  "Moid": "58e6de34e138234f057fe8cd",
  "CreateTime": "2017-04-06T17:32:52.965-07:00",
  "ModTime": "2017-04-06T17:32:52.975-07:00",
  "Tags": [
    {
      "Key": "Site",
      "Value": "London"
    },
    {
      "Key": "Environment",
      "Value": "Production"
    }
  ]
}

Example 4: Query RackUnit resources where the "Owner" property contains the primitive value '58e6de34e138234f057fe800'

GET /api/v1/compute/RackUnits?$filter=Owners/any(v:v eq '58e6de34e138234f057fe800')

Output

{
  "Moid": "58e6de34e138234f057fe8cd",
  "CreateTime": "2017-04-06T17:32:52.965-07:00",
  "ModTime": "2017-04-06T17:32:52.975-07:00",
  "Owners": [
    "58e6de34e138234f057fe800",
    "58e6de34e138234f057fe801"
  ]
}

Date and Time Functions

"now()" function

The "now()" function evaluates to the current system time. The now() function can be combined with other operators to filter REST resources based on duration. For example, to query the rack unit servers that were created less than 60 days ago, the following query filter can be used:

GET /api/v1/compute/RackUnits?$filter=CreateTime gt now() sub 'P60D'

"maxdatetime()" function

The "maxdatetime()" function returns the latest possible point in time as a DateTime value.

"mindatetime()" function

The "mindatetime()" function returns the earliest possible point in time as a DateTime value.

Arithmetic operators

Addition

The "add" operator adds the left and right numeric operands. The add operator is also valid for the following time-related operands:

DateTime add Duration results in a DateTime
Duration add Duration results in a Duration

Substraction

The "sub" operator subtracts the right numeric operand from the left numeric operand. The sub operator is also valid for the following time-related operands:

DateTime sub Duration results in a DateTime
Duration sub Duration results in a Duration
DateTime sub DateTime results in a Duration

Multiplication

The mul operator multiplies the left and right numeric operands.

Division

The div operator divides the left numeric operand by the right numeric operand. If the right operand is zero, the request fails.

Modulo

The mod operator returns the remainder when the left integral operand is divided by the right integral operand. If the right operand is zero, the request fails.

$select Query Option: Selecting properties in the HTTP response

The $select query option allows clients to request a specific set of properties for each entity or complex type. The value of the $select option is a comma-separated list of property names.

The $select option is not intended to be a query filter. For query filters, see the $filter operator.

The ability to select which properties are returned in the HTTP response can help to minimize network traffic between the client and the Intersight Web service and improve the performance of the client. This can be especially useful for mobile applications.

Example: Query compute.RackUnit managed objects, where each response managed object is represented with three properties: Vendor, Model, and Serial (instead of having the full JSON output for compute.RackUnit). >Note: The "Moid" is always included in the response regardless of what is specified in the $select query parameter.

GET /api/v1/compute/RackUnits?$select=Vendor,Model,Serial

HTTP Response:

{
  "Results": [
    {
      "Model": "HX220C-M5SX",
      "Moid": "59696db9a94c04000137f683",
      "Serial": "WZP21120SP9",
      "Vendor": "Cisco Systems Inc"
    },
    {
      "Model": "UCSC-C240-M5SN",
      "Moid": "59696f3ba94c04000137f8d4",
      "Serial": "WZP211704KM",
      "Vendor": "Cisco Systems Inc"
    },
    {
      "Model": "HX220C-M5SX",
      "Moid": "59696faba94c04000137fc13",
      "Serial": "WZP21120SP1",
      "Vendor": "Cisco Systems Inc"
    },
  ]
}

$top and $skip Query Options: Pagination

The $top and $skip query options are used to paginate the results. A client can request a particular page of managed objects by specifying $top and $skip. You can specify $orderby to sort the results such that paginated results are returned in a predictable order. For example, you can specify $orderby=CreationTime to paginate results sorted by creation time.

The $top query option requests the maximum number of managed objects that are included in the HTTP response. If more than $top managed objects match the $filter criteria, at most $top results are returned. If $top is not specified, the value of $top is set to 100 by default. The maximum value for $top is 1000.

The $skip query option requests the number of managed objects that are to be skipped and not included in the result.

Example: Query compute.RackUnit managed objects, return a page that skips the first 100 objects of the collection; return at most 20 elements.

GET /api/v1/compute/RackUnits?$top=20&skip=100

$top and $skip can be combined with other operators such as $filter and $select. For example, to request a page containing 20 compute.RackUnit managed objects and skip 100 objects. Output should select Vendor, Model, Serial properties.

GET /api/v1/compute/RackUnits?$top=20&skip=100&$select=Vendor,Model,Serial

$orderby Query Option: Sorting results

The $orderby query option allows clients to request resources in a particular order. The value of the $orderby option is a comma-separated list of property names. When multiple properties are specified, the Intersight Web service sorts the results from left to right, i.e. sorting the result with the first property, then second property, etc.

When the "desc" character is appended to the property name with a space, the results are sorted in descending order.

Example: Query compute.RackUnit managed objects, order result in ascending order by Model

GET /api/v1/compute/RackUnits?$select=Vendor,Model,Serial&orderby=Model

Request a list of compute.RackUnit managed objects, order result in descending order by Model

GET /api/v1/compute/RackUnits?$select=Vendor,Model,Serial&orderby=Model desc

$count Query Option: Counting results

The $count query option allows clients to request a count of the matching resources included with the resources in the response. The $count query option has a Boolean value of true or false.

Example: Return the total count of the compute.RackUnit managed objects.

GET /api/v1/compute/RackUnits?$count=true

Output:

{
  "Count": 7493
}

$inlinecount Query Option: Returning managed objects and count of objects

The $inlinecount query option allows clients to request both the resources and the count of resources in the response. The $inlinecount query option is an enum value which can be set to allpages or none. When the value is set to allpages, the response includes the count of the objects matching the optional $filter query parameter, regardless of the $top option. Setting the value of $inlinecount to none has no effect.

For example, this can be used to paginate and determine how many objects can be queried.

Example: Request compute.RackUnit objects and the count of these objects.

Filter by server model: $filter=Model eq 'HXAF220C-M5SX'
Sort by serial number: $orderby=Serial
Return the first two objects: $top=2
Include the count of objects matching the $filter criteria: $inlinecount=allpages
Return the Model and Serial properties in the response: $select=Model,Serial

GET /api/v1/compute/RackUnits?$inlinecount=allpages&$top=2&$select=Model,Serial&$filter=Model eq 'HXAF220C-M5SX'&$orderby=Serial

Output:

In this example, the response has two server objects because $top=2 was requested. The response also includes "Count": 15 to indicate the number of servers matching the $filter=Model eq 'HXAF220C-M5SX' criteria.

{
  "ObjectType": "compute.RackUnit.List",
  "Count": 15,
  "Results": [
    {
      "ClassId": "compute.RackUnit",
      "Model": "HXAF220C-M5SX",
      "Moid": "5ef76d7e6176752d37448c7c",
      "ObjectType": "compute.RackUnit",
      "Serial": "WZP220216UA"
    },
    {
      "ClassId": "compute.RackUnit",
      "Model": "HXAF220C-M5SX",
      "Moid": "5cdaf1946176752d31befa92",
      "ObjectType": "compute.RackUnit",
      "Serial": "WZP220216UQ"
    }
  ]
}

$apply Query Option

Aggregation behavior is triggered using the query option $apply. The $apply option takes a sequence of set transformations, separated by forward slashes to express that they are consecutively applied, e.g. the result of each transformation is the input to the next transformation.

Aggregation Method "min"

The standard aggregation method min can be applied to values with a totally ordered domain to return the smallest of the non-null values or null if there are no non-null values.

Example: determine the minimum available memory per server, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property
For each model, apply the "min" aggregate function over the "AvailableMemory" property
Using the "as" keyword, name the aggregate result as "MinAvailableMemory"

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate(AvailableMemory with min as MinAvailableMemory))

Output

  {
    "MinAvailableMemory": 16384,
    "Model": "UCSC-C220-M5S"
  },
  {
    "MinAvailableMemory": 262144,
    "Model": "HXAF240C-M4SX"
  },

Aggregation Method "max"

The standard aggregation method max can be applied to values with a totally ordered domain to return the largest of the non-null values, or null if there are no non-null values.

Example: determine the maximum available memory per server, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property
For each model, apply the " max" aggregate function over the "AvailableMemory" property
Using the "as" keyword, name the aggregate result as "MaxAvailableMemory"

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate(AvailableMemory with max as MaxAvailableMemory))

Output

{
  "MaxAvailableMemory": 524288,
  "Model": "UCSC-C220-M5S"
},
{
  "MaxAvailableMemory": 1048576,
  "Model": "HXAF240C-M4SX"
},

Aggregation Method "average"

The standard aggregation method average can be applied to numeric values to return the sum of the non-null values divided by the count of the non-null values, or null if there are no non-null values.

Example: determine the average amount of available memory per server, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property
For each model, apply the "average" aggregate function over the "AvailableMemory" property
Using the "as" keyword, name the aggregate result as "AverageAvailableMemory"

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate(AvailableMemory with average as AverageAvailableMemory))

Output

{
  "AverageAvailableMemory": 95506.73170731707,
  "Model": "UCSC-C220-M5S"
},
{
  "AverageAvailableMemory": 478672.6343612335,
  "Model": "HXAF240C-M4SX"
},

Aggregation Method "sum"

The standard aggregation method sum can be applied to numeric values to return the sum of the non-null values, or null if there are no non-null values.

Example: calculate the sum of the available memory per server, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property
For each model, apply the "sum" aggregate function over the "AvailableMemory" property
Using the "as" keyword, name the aggregate result as "TotalAvailableMemory"

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate(AvailableMemory with sum as TotalAvailableMemory))

Output

  {
    "TotalAvailableMemory": 2899968,
    "Model": "UCSC-C220-M5S"
  },
  {
    "TotalAvailableMemory": 108658688,
    "Model": "HXAF240C-M4SX"
  },

Aggregation Method "$count"

The standard aggregation method $count can be applied to return the count of the non-null values.

Example: determine the number of servers, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property
For each model, apply the "$count" aggregate function
Using the "as" keyword, name the aggregate result as "Total"

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate($count as Total))

Output

  {
    "Total": 20,
    "Model": "UCSC-C220-M5S"
  },
  {
    "Total": 30,
    "Model": "HXAF240C-M4SX"
  },

Transformation "groupby"

The groupby transformation takes one or two parameters and

Splits the initial set into subsets where all instances in a subset have the same values for the grouping properties specified in the first parameter,
Applies set transformations to each subset according to the second parameter, resulting in a new set of potentially different structure and cardinality,
Ensures that the instances in the result set contain all grouping properties with the correct values for the group,
Concatenates the intermediate result sets into one result set.

Keyword "as"

Aggregate expressions can define an alias using the as keyword, followed by a SimpleIdentifier

Ordering results of aggregate queries

Results of aggregate queries may be ordered in ascending or descending order.

Example: determine the number of servers, grouped by server platform. This can be done by applying the following aggregate transformation:

Group Rack Units resources by "Model" property.
For each model, apply the "$count" aggregate function.
Using the "as" keyword, name the aggregate result as "Total".
Add $orderby parameter to sort with the "Total" field.

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate($count as Total))&$orderby=Total

Output

  {
    "Total": 3,
    "Model": "UCSC-C220-M5S"
  },
  {
    "Total": 6,
    "Model": "HXAF240C-M4SX"
  },
  {
    "Total": 7,
    "Model": "HXAF240C-M5SX"
  },

Now sort in descending order for the same aggregate query:

GET /api/v1/compute/RackUnits?$apply=groupby((Model), aggregate($count as Total))&$orderby=Total desc

Output

  {
    "Total": 7,
    "Model": "HXAF240C-M5SX"
  },
  {
    "Total": 6,
    "Model": "HXAF240C-M4SX"
  },
  {
    "Total": 3,
    "Model": "UCSC-C220-M5S"
  },

The $expand query option specifies the related resources to be included in line with retrieved resources.

Use $select with $expand to reduce the response body size to get the required fields.
If the expanded item is a collection, you can restrict your collection using $top, $skip and $orderby.
You can expand all relationships within an MO. There is no limit on the recursive expand you can use, but the api might time out if you have too many expand.
Use comma for multiple expand, for example $expand=Parent, Ancestor
When you use multiple options within expand, use the encoded value of semicolon (%3B). For example, Profiles($select=Name,ConfigResult%3B$expand=ConfigResult)

Example: Get PhysicalSummaries, then expand Device Registration Relationship with it. Use expand on RegisteredDevice and select DeviceHostname, ClaimedByUser from it. Further expand ClaimedByUser to get the user's firstname and email.

GET /api/v1/compute/PhysicalSummaries?$select=Name,RegisteredDevice&$expand=RegisteredDevice($select=DeviceHostname,ClaimedByUser%3B$expand=ClaimedByUser($select=Email,FirstName))

Output

"Results": [
   {
      "Moid": "5c62e7236176752d3007cacf",
      "Name": "Berkeley-1-1",
      "ObjectType": "compute.PhysicalSummary",
      "RegisteredDevice": {
        "ClaimedByUser": {
          "Email": "admin@local",
          "FirstName": "admin",
          "Moid": "5c62e5c37564612d3041ca04",
          "ObjectType": "iam.User"
        },
        "DeviceHostname": [
          "Berkeley"
        ],
        "Moid": "5c62e7186f72612d301b869a",
        "ObjectType": "asset.DeviceRegistration"
      }
    },
    {
      "Moid": "5c62e7236176752d3007cad6",
      "Name": "Berkeley-1-2",
      "ObjectType": "compute.PhysicalSummary",
      "RegisteredDevice": {
        "ClaimedByUser": {
          "Email": "admin@local",
          "FirstName": "admin",
          "Moid": "5c62e5c37564612d3041ca04",
          "ObjectType": "iam.User"
        },
        "DeviceHostname": [
          "Berkeley"
        ],
        "Moid": "5c62e7186f72612d301b869a",
        "ObjectType": "asset.DeviceRegistration"
      }
    },
   ]
}

Example: Get a Syslog Policy, select name,and profiles from it. Then expand Profiles relationship for the policy and ConfigResults for the Profile:

Recursive $expand. Here Profile is expanded first and then ConfigResults is expanded for each profile.

GET /api/v1/syslog/Policies/5c6492766275722d3070d0d5?$expand=Profiles($select=Name,ConfigResult%3B$expand=ConfigResult($select=ConfigStage,ConfigState))

Output

"Results": : {
      "Moid": "5c6492766275722d3070d0d5",
      "Name": "syslogpolicyappvm",
      "ObjectType": "syslog.Policy",
      "Profiles": [
        {
          "ConfigResult": {
            "ConfigStage": "",
            "ConfigState": "",
            "Moid": "5c64928a77696e2d3073a6cb",
            "ObjectType": "server.ConfigResult"
          },
          "Moid": "5c64928a77696e2d3073a6ca",
          "Name": "appvmprofile",
          "ObjectType": "server.Profile"
        },
        {
          "ConfigResult": {
            "ConfigStage": "",
            "ConfigState": "",
            "Moid": "5c6492ed77696e2d3073a6d5",
            "ObjectType": "server.ConfigResult"
          },
          "Moid": "5c6492ed77696e2d3073a6d4",
          "Name": "devvmprofile",
          "ObjectType": "server.Profile"
        }
      ]
    }

Webhook Limitations

The Webhooks feature supports the ability to provide OData filter ($filter operator). The following functions and operators are not supported in the Webhook OData $filter:

String functions: contains
Logical operators: in
Lambda operators: any
Date and time functions: now(), maxdatetime(), mindatetime()

Search API

Intersight provides search API that allows users to search for one or more resources in Intersight. The URL for the search API is GET /api/v1/search/SearchItems. This API allows to request resources of multiple types. API supports the ODATA query options such as $top, $skip, $orderby, $filter, $select, $count and Lambda operators as described above. It does not support $apply, and $expand options described above.

Example

Query RackUnit (ObjectType eq 'compute.RackUnit') resources where the model property is not ('HX220C-M5SX' or 'HX220C-M5S').

GET /api/v1/search/SearchItems?$select=Vendor,Model,Serial&$filter=(ObjectType eq compute.RackUnit) and not(Model eq 'HX220C-M5SX' or Model eq 'HX220C-M5S')

Example: Query all types of Policy resources and return the first 3 policies ordered by Modified Time.

GET /api/v1/search/SearchItems?$filter=(IndexMotypes eq 'policy.AbstractPolicy') &$select=Name,ObjectType,Moid&$top=3&orderby=ModTime desc

Output

{
  "Count": 233,
  "Results": [
    {
      "IndexMoid": "",
      "IndexMotype": "iam.LdapPolicy",
      "IndexMotypes": [
        "iam.LdapPolicy",
        "policy.AbstractPolicy",
        "mo.BaseMo"
      ],
      "Moid": "5b046009326230397a2e31cf",
      "Name": "SentryIssue528"
    },
    {
      "IndexMoid": "",
      "IndexMotype": "hyperflex.SysConfigPolicy",
      "IndexMotypes": [
        "hyperflex.SysConfigPolicy",
        "policy.AbstractPolicy",
        "mo.BaseMo"
      ],
      "Moid": "5a4d46bc6278707336319f9f",
      "Name": "ggggg-sys-config-policy"
    },
    {
      "IndexMoid": "",
      "IndexMotype": "hyperflex.SysConfigPolicy",
      "IndexMotypes": [
        "hyperflex.SysConfigPolicy",
        "policy.AbstractPolicy",
        "mo.BaseMo"
      ],
      "Moid": "5afb10853662356667c5c82f",
      "Name": "lsilvest-test-sys-config-policy"
    }
  ]
}

Search Tags API

Intersight provides Tags Listing API to retrieve and search Tags Key and Values across various resources in Intersight. The URL is GET /api/v1/search/TagItems. This API supports the ODATA query options such as $top, $skip, $orderby, $filter, $count and Lambda operators as described above. It does not support $apply and $expand options.

Example: Query All Tags for all Resources

GET /api/v1/search/TagItems

Output

{
  "Count": 46,
  "Results": [
    {
      "Key": "sad",
      "Count": 50,
      "Values": [
        "sad"
      ]
    },
    {
      "Key": "test",
      "Count": 23,
      "Values": [
        "567123",
        "123",
        "333",
        "234",
        "Abc123",
        "TesT123",
        "tag"
      ]
    },
    {
      "Key": "Site",
      "Count": 14,
      "Values": [
        "2",
        "1",
        "SJC"
      ]
    },
    {
      "Key": "Floor",
      "Count": 9,
      "Values": [
        "2",
        "4",
        "1"
      ]
    },
    {
      "Key": "Location",
      "Count": 2,
      "Values": [
        "SJC",
        "test"
      ]
    },
    .....
  ]
}

Example: Query all Tags for all Policies where Tags Key equals Floor

GET /api/v1/search/SearchItems?$filter=(IndexMotypes eq policy.AbstractPolicy) and Tags/any(t:t/Key eq 'Floor')

Output

{
  "Count": 1,
  "Results": [
    {
      "Key": "Floor",
      "Count": 9,
      "Values": [
        "2",
        "4",
        "1"
      ]
    }
  ]
}

Example: Query all Tags for all Policies and select only Tags.Key and not Values.

GET /api/v1/search/SearchItems?$filter=(IndexMotypes eq policy.AbstractPolicy)&$select=Tags.Key

Output

{
  "Count": 21,
  "Results": [
    {
      "Key": "test"
    },
    {
      "Key": "Floor"
    },
    {
      "Key": "cisco.meta.attachableserviceobject.hyperflex.ClusterProfile"
    },
    {
      "Key": "cisco.meta.managementplatform.standalone"
    },
    {
      "Key": "asd"
    },
    {
      "Key": "cisco.meta.managementplatform.fi"
    },
    {
      "Key": "Location"
    },
    {
      "Key": "MyTags"
    },
    {
      "Key": "Site"
    },
    {
      "Key": "t1"
    },
    ......
  ]
}

Global Search API

Intersight provides global search API that allows users to search for one or more resources in Intersight that matches certain attributes. The URL for the globalsearch API is POST /api/v1/search/SuggestItems.

You can search for all objects by their names or tags (keys and values), and the search returns the top matches grouped by object type. Hyphens and spaces are used as separators, and any term entered after a separator is considered as a new search keyword.

The global search returns all matches to a keyword or keywords. For example, if you have two profiles titled Cisco-Profile-Example and My Profile example2 in Cisco Intersight, and you search for "profile" or "Example", both these profiles are returned in the search result.

The keyword for the search is provided in the 'SuggestTerm' attribute of the request body. Additional filters options can be provided via the ODATA query options in the rawQuery field of the request body. RawQuery supports $filter, and $select options. The types of resources that are searched will be restricted using the "type" attribute in the request body. You can add one or more types in the type field.

Subset of attributes that are globally searchable differ for each resource. You can search for the following resource by their attributes:

Servers: Server model, name, tags, serial number, Management IP address, firmware
    
Policies: Policy name, tags
    
HyperFlex Clusters: Cluster name, tags
    
Profiles—Profile: description, name, tags
    
FIs: Model, name, serial number, tags, Management IP address
    
Alarms: Severity (for example - Warning, Critical), name, description, tags, code(alarm code)

Example

Query Server Views, Profiles, and Alarms, and Policies resources where attributes matches vic.

POST /api/v1/search/SuggestItems
 
JSON
{
    "SuggestTerm":"vic",
    "type":"compute.PhysicalSummary,cond.Alarm,policy.AbstractProfile,policy.AbstractPolicy",
    "rawQuery":"$select=Moid,DisplayNames,ObjectType,CreateTime,ModTime,Severity,Description,FaultSummary,Name&$filter=not(Severity eq 'Cleared')"
    
}

Query Syntax

Supported Types

String

Number

Date and Time

Time of day

Duration

Parenthesis: specifying operator precedence

Referencing Properties By Name

$filter Query Option: Filtering the Resources

Logical Operators

"Equal" Operator

"Not Equal" Operator

"Greater Than" Operator

"Less Than" Operator

"Greater Than Or Equal" Operator

"Less Than Or Equal" Operator

"And" Operator

"Or" Operator

"Not" Operator

"In" Operator

String Functions

"contains" Function

"startsWith" Function

"endswith" Function

"tolower" Function

"toupper" Function

Lambda Operators

Lambda "any" Operator

Date and Time Functions

"now()" function

"maxdatetime()" function

"mindatetime()" function

Arithmetic operators

Addition

Substraction

Multiplication

Division

Modulo

$select Query Option: Selecting properties in the HTTP response

$top and $skip Query Options: Pagination

$orderby Query Option: Sorting results

$count Query Option: Counting results

$inlinecount Query Option: Returning managed objects and count of objects

$apply Query Option

Aggregation Method "min"

Aggregation Method "max"

Aggregation Method "average"

Aggregation Method "sum"

Aggregation Method "$count"

Transformation "groupby"

Keyword "as"

Ordering results of aggregate queries

$expand Query Option: Returning related resources

Webhook Limitations

Search API

Search Tags API

Global Search API