Aggregate API examples

These examples demonstrate how to perform a REST query using cURL commands, and the data returned for each command.

Sample response formats

Figure 1. JSON format
{
    "result": {
        "stats": {
            "count": "6",
            "max": {
                "number": "INC0000053"
            },
            "min": {
                "priority": "1",
                "number": "INC0000015"
            }
        }
    }
}
Figure 2. XML format
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <result>
      <stats>
         <min>
            <priority>1</priority>
            <number>INC0000007</number>
         </min>
         <max>
            <number>INC0010004</number>
         </max>
         <count>16</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value />
      </groupby_fields>
   </result>
   <result>
      <stats>
         <min>
            <priority>4</priority>
            <number>INC0000010</number>
         </min>
         <max>
            <number>INC0000012</number>
         </max>
         <count>2</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value>Database</value>
      </groupby_fields>
   </result>
   <result>
      <stats>
         <min>
            <priority>1</priority>
            <number>INC0000005</number>
         </min>
         <max>
            <number>INC0000050</number>
         </max>
         <count>9</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value>Hardware</value>
      </groupby_fields>
   </result>
   <result>
      <stats>
         <min>
            <priority>1</priority>
            <number>INC0000002</number>
         </min>
         <max>
            <number>INC0000039</number>
         </max>
         <count>5</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value>Network</value>
      </groupby_fields>
   </result>
   <result>
      <stats>
         <min>
            <priority>1</priority>
            <number>INC0000001</number>
         </min>
         <max>
            <number>INC0000055</number>
         </max>
         <count>12</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value>Service Desk</value>
      </groupby_fields>
   </result>
   <result>
      <stats>
         <min>
            <priority>1</priority>
            <number>INC0000006</number>
         </min>
         <max>
            <number>INC0000053</number>
         </max>
         <count>9</count>
      </stats>
      <groupby_fields>
         <field>assignment_group</field>
         <value>Software</value>
      </groupby_fields>
   </result>
</response>

Specifying a query

You can specify a query by using either the sysparm_query parameter or key-value pairs.

Using sysparm_query:
curl -H "Accept:application/json" --user admin:admin
      "http://<instance>.service-now.com/api/now/stats/incident?sysparm_count=true&sysparm_max_fields=number&sysparm_min_fields=number,priority&sysparm_query=active=true&assignment_group=software"
Using key-value pairs:
curl -H "Accept:application/json" --user admin:admin
      "http://<instance>.service-now.com/api/now/stats/incident?sysparm_count=true&sysparm_max_fields=number&sysparm_min_fields=number,priority&active=true&assignment_group=Software"
Figure 3. Response
{
    "result": {
        "stats": {
            "count": "6",
            "max": {
                "number": "INC0000053"
            },
            "min": {
                "priority": "1",
                "number": "INC0000015"
            }
        }
    }
}

Grouping results

You can group results by using the sysparm_group_by parameter.
curl -H "Accept:application/json" --user admin:admin
        "http://<instance>.service-now.com/api/now/stats/incident?sysparm_count=true&sysparm_max_fields=number&sysparm_min_fields=number,priority&sysparm_group_by=assignment_group"
Figure 4. Response
{
    "result": [
        {
            "stats": {
                "count": "13",
                "max": {
                    "number": "INC0000048"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000007"
                }
            },
            "groupby_fields": [
                {
                    "value": "",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "2",
                "max": {
                    "number": "INC0000012"
                },
                "min": {
                    "priority": "4",
                    "number": "INC0000010"
                }
            },
            "groupby_fields": [
                {
                    "value": "287ee6fea9fe198100ada7950d0b1b73",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "9",
                "max": {
                    "number": "INC0000050"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000005"
                }
            },
            "groupby_fields": [
                {
                    "value": "8a5055c9c61122780043563ef53438e3",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "5",
                "max": {
                    "number": "INC0000039"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000002"
                }
            },
            "groupby_fields": [
                {
                    "value": "287ebd7da9fe198100f92cc8d1d2154e",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "12",
                "max": {
                    "number": "INC0000055"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000001"
                }
            },
            "groupby_fields": [
                {
                    "value": "d625dccec0a8016700a222a0f7900d06",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "9",
                "max": {
                    "number": "INC0000053"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000006"
                }
            },
            "groupby_fields": [
                {
                    "value": "8a4dde73c6112278017a6a4baf547aa7",
                    "field": "assignment_group"
                }
            ]
        }
    ]
}

Specifying a display value format

You can control if reference and choice field values appear as a sys_id, a label value, or both by using the sysparm_display_value parameter.
curl -H "Accept:application/json" --user admin:admin
      "http://<instance>.service-now.com/api/now/stats/incident?sysparm_count=true&sysparm_max_fields=number&sysparm_min_fields=number,priority&sysparm_group_by=assignment_group&sysparm_display_value=true"
Figure 5. Response
{
    "result": [
        {
            "stats": {
                "count": "13",
                "max": {
                    "number": "INC0000048"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000007"
                }
            },
            "groupby_fields": [
                {
                    "value": "",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "2",
                "max": {
                    "number": "INC0000012"
                },
                "min": {
                    "priority": "4",
                    "number": "INC0000010"
                }
            },
            "groupby_fields": [
                {
                    "value": "Database",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "9",
                "max": {
                    "number": "INC0000050"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000005"
                }
            },
            "groupby_fields": [
                {
                    "value": "Hardware",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "5",
                "max": {
                    "number": "INC0000039"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000002"
                }
            },
            "groupby_fields": [
                {
                    "value": "Network",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "12",
                "max": {
                    "number": "INC0000055"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000001"
                }
            },
            "groupby_fields": [
                {
                    "value": "Service Desk",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "9",
                "max": {
                    "number": "INC0000053"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000006"
                }
            },
            "groupby_fields": [
                {
                    "value": "Software",
                    "field": "assignment_group"
                }
            ]
        }
    ]
}

Ordering grouped fields

You can order groups of results based on the values in one or more specified fields by using the sysparm_orderby parameter.
curl -H "Accept:application/json" --user admin:admin
      "http://<instance>.service-now.com/api/now/stats/incident?sysparm_count=true&sysparm_max_fields=number&sysparm_min_fields=number,priority&sysparm_group_by=assignment_group&sysparm_display_value=true&sysparm_query=active=true&sysparm_orderby=assignment_group^DESC"
Figure 6. Response
{
    "result": [
        {
            "stats": {
                "count": "6",
                "max": {
                    "number": "INC0000053"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000015"
                }
            },
            "groupby_fields": [
                {
                    "value": "Software",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "5",
                "max": {
                    "number": "INC0000055"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000017"
                }
            },
            "groupby_fields": [
                {
                    "value": "Service Desk",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "3",
                "max": {
                    "number": "INC0000039"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000002"
                }
            },
            "groupby_fields": [
                {
                    "value": "Network",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "4",
                "max": {
                    "number": "INC0000050"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000005"
                }
            },
            "groupby_fields": [
                {
                    "value": "Hardware",
                    "field": "assignment_group"
                }
            ]
        },
        {
            "stats": {
                "count": "12",
                "max": {
                    "number": "INC0000048"
                },
                "min": {
                    "priority": "1",
                    "number": "INC0000007"
                }
            },
            "groupby_fields": [
                {
                    "value": "",
                    "field": "assignment_group"
                }
            ]
        }
    ]
}