REST API ReferenceServiceNow provides extensive access to instances through a set of RESTful APIs. Below you will find a list of the available endpoints with the latest information. For more information about a particular endpoint, click on it in the left pane to view a description of the endpoint, applicable query parameters, a sample request in multiple formats, and a sample response payload.Additionally, you can discover these APIs from within your instance by using the REST API Explorer. If you don't find an API that meets your needs you can create custom REST APIs on ServiceNow using our Scripted REST API feature as of the Geneva release.If you are new to REST APIs check out our Getting started with REST page.ServiceNow REST APIs support Basic Authentication and OAuth 2.0 to authenticate requests.ServiceNow REST APIs are versioned. Use the version selector shown in the lower left corner of this page to choose which version of the documentation you would like to see.

Aggregate API

The ServiceNow Aggregate REST API allows you to compute aggregate statistics about existing table and column data.

Aggregate API.GET /now/stats/{tableName}

This method retrieves records for the specified table and performs aggregate functions on the returned values.

Versioned URL: /api/now/v1/stats/{tableName}
Default URL: /api/now/stats/{tableName}
Additional info:

Available aggregate functions

You can specify which aggregate functions to perform by using either the sysparm_<aggregate>_fields parameter or sysparm_having=<aggregate>^field^operator^value parameter, substituting <aggregate> for one of these aggregate functions:

Status code
200: Indicates the request completed successfully.

Sample curl request
curl "https://instance.service-now.com/api/now/stats/incident?sysparm_avg_fields=reassignment_count%2Cbusiness_stc&sysparm_group_by=assignment_group" \ --request GET \ --header "Accept:application/json" \ --user 'admin':'admin'

Sample python request
#Need to install requests package for python #easy_install requests import requests # Set the request parameters url = 'https://instance.service-now.com/api/now/stats/incident?sysparm_avg_fields=reassignment_count%2Cbusiness_stc&sysparm_group_by=assignment_group' # Eg. User name="admin", Password="admin" for this code sample. user = 'admin' pwd = 'admin' # Set proper headers headers = {"Content-Type":"application/xml","Accept":"application/xml"} # Do the HTTP request response = requests.get(url, auth=(user, pwd), headers=headers ) # Check for HTTP codes other than 200 if response.status_code != 200: print('Status:', response.status_code, 'Headers:', response.headers, 'Error Response:',response.json()) exit() # Decode the JSON response into a dictionary and use the data data = response.json() print(data)

Name	Type	Description
sysparm_query	An encoded query. For example: (sysparm_query=active=true)(sysparm_query=caller_id=javascript:gs.getUserID()^active=true)
sysparm_group_by	The fields to group the returned data by. You can specify multiple fields by separating each with a comma, such as sysparm_group_by=priority,state.
sysparm_having	An additional query allowing you to filter the data based on an aggregate operation. The value for this parameter must follow the syntax aggregate^field^operator^value, such ascount^priority^>^3 to obtain the number of records within the query results with a priority greater than 3. You can specify multiple queries by separating each with a comma, such ascount^state^=^1,avg^priority^>^3.
sysparm__fields	The list of fields you want to perform each aggregate operation on. You can specify multiple fields by separating each with a comma. For example, to get the average values from the duration and priority fields, use sysparm_avg_fields=duration,priority. Note: You must specify this parameter, the sysparm_count parameter, or both for your query to return meaningful results. If neither parameter is passed, no aggregate operation is performed.
sysparm_count	A boolean flag. You can set this parameter to true for the number of records returned by the query. Note: You must specify this parameter, the sysparm_<aggregate>_fields parameter, or both for your query to return meaningful results. If neither parameter is passed, no aggregate operation is performed.
sysparm_display_value	Data retrieval operation when grouping by reference or choice fields. Based on this value, the query returns either the display value, the actual value in the database, or both. true returns display values for all of the fields. false returns actual values from the database. If a value is not specified, this parameter defaults to false. all returns both actual and display values. There is no preferred method for setting this parameter; however, specifying the display value may cause performance issues because it is not reading directly from the database and may include referencing other fields and records. For more information on display values and actual values, see Table API FAQs (KB0534905).
sysparm_order_by	A list of values to order grouped results by. You can specify an order using a field or an aggregate. For example, if you specify sysparm_order_by=AVG^state, groups of results with lower average state values are returned first. You can also order by COUNT to arrange groups of records by the number of records in each group. When you specify an order, groups are ordered in ascending order by default. Use ^DESC to sort in descending order, such as sysparm_order_by=state^DESC.
Key-Value Pairs	An alternative to using the sysparm_query parameter. You can filter a query using key-value pairs where the key is the name of a field. For example, instead of using the parameter &sysparm_query=active=true, you can use &active=true. You can use the display value when the field is a choice or reference type field, such as &state=closed instead of &state=7. To specify multiple key-value pairs, separate each with an ampersand, such as &active=true&assigned_to=john.smith.