The ServiceNow Aggregate API provides endpoints to compute aggregate statistics (count, average, min, max, sum) against records in any ServiceNow table. It supports grouping and filtering results, making it useful for reporting and dashboard data retrieval.
openapi: 3.1.0
info:
title: ServiceNow Aggregate API
description: >-
The ServiceNow Aggregate API provides endpoints to compute aggregate
statistics against records in any ServiceNow table. It supports count,
average, minimum, maximum, and sum operations with optional grouping and
filtering, making it useful for reporting dashboards and analytics
integrations.
version: 'Yokohama'
contact:
name: ServiceNow Support
url: https://support.servicenow.com
termsOfService: https://www.servicenow.com/terms-of-use.html
externalDocs:
description: ServiceNow Aggregate API Documentation
url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_AggregateAPI.html
servers:
- url: https://{instance}.service-now.com/api/now
description: ServiceNow Instance
variables:
instance:
default: instance
description: Your ServiceNow instance name
tags:
- name: Aggregate Statistics
description: >-
Operations for computing aggregate statistics on ServiceNow table records
including count, sum, average, minimum, and maximum values.
security:
- basicAuth: []
- oauth2: []
paths:
/stats/{tableName}:
get:
operationId: getAggregateStats
summary: Servicenow Retrieve Aggregate Statistics for a Table
description: >-
Computes aggregate statistics for records in the specified table.
Supports count, sum, average, minimum, and maximum calculations with
optional query filtering and group-by fields. Multiple aggregate types
can be requested in a single call.
tags:
- Aggregate Statistics
parameters:
- $ref: '#/components/parameters/tableName'
- name: sysparm_query
in: query
required: false
description: >-
An encoded query string to filter records before aggregation.
Uses the same syntax as the Table API sysparm_query parameter.
schema:
type: string
example: 'active=true^priority=1'
- name: sysparm_count
in: query
required: false
description: >-
When set to true, returns the count of records matching the query.
schema:
type: boolean
default: false
example: 42
- name: sysparm_sum_fields
in: query
required: false
description: >-
A comma-separated list of numeric fields for which to calculate
the sum.
schema:
type: string
example: 'reassignment_count,reopen_count'
- name: sysparm_avg_fields
in: query
required: false
description: >-
A comma-separated list of numeric fields for which to calculate
the average.
schema:
type: string
example: example_value
- name: sysparm_min_fields
in: query
required: false
description: >-
A comma-separated list of fields for which to find the minimum
value.
schema:
type: string
example: example_value
- name: sysparm_max_fields
in: query
required: false
description: >-
A comma-separated list of fields for which to find the maximum
value.
schema:
type: string
example: example_value
- name: sysparm_group_by
in: query
required: false
description: >-
A comma-separated list of fields by which to group the aggregated
results. Each unique combination of group-by field values produces
a separate result entry.
schema:
type: string
example: 'priority,state'
- name: sysparm_order_by
in: query
required: false
description: >-
The field by which to order the grouped results.
schema:
type: string
example: example_value
- name: sysparm_having
in: query
required: false
description: >-
An additional filter applied after aggregation to restrict which
groups are returned based on aggregate values.
schema:
type: string
example: example_value
- name: sysparm_display_value
in: query
required: false
description: >-
Controls whether display values or actual values are returned for
group-by fields.
schema:
type: string
enum:
- 'true'
- 'false'
- all
default: 'false'
example: 'true'
responses:
'200':
description: >-
Successful response containing the computed aggregate statistics.
content:
application/json:
schema:
type: object
properties:
result:
$ref: '#/components/schemas/AggregateResult'
examples:
Getaggregatestats200Example:
summary: Default getAggregateStats 200 response
x-microcks-default: true
value:
result:
stats:
count: 42
group_by:
- {}
'401':
description: Unauthorized. Authentication credentials are missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getaggregatestats401Example:
summary: Default getAggregateStats 401 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
'404':
description: >-
Not found. The specified table does not exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
Getaggregatestats404Example:
summary: Default getAggregateStats 404 response
x-microcks-default: true
value:
error:
message: example_value
detail: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Basic authentication with ServiceNow credentials. The user must have
appropriate table read access.
oauth2:
type: oauth2
description: OAuth 2.0 authentication using ServiceNow's OAuth provider.
flows:
password:
tokenUrl: https://{instance}.service-now.com/oauth_token.do
scopes: {}
parameters:
tableName:
name: tableName
in: path
required: true
description: >-
The name of the ServiceNow table on which to compute aggregate
statistics.
schema:
type: string
example: incident
schemas:
AggregateResult:
type: object
description: >-
The aggregate statistics result. Structure varies based on the
requested aggregate types and group-by fields.
properties:
stats:
type: object
description: >-
Contains the computed aggregate values organized by field name
and aggregate type.
properties:
count:
type: string
description: The total count of records matching the query.
additionalProperties: true
example: example_value
group_by:
type: array
description: >-
When group-by fields are specified, contains an entry for each
unique group with its aggregate values.
items:
type: object
additionalProperties: true
example: []
Error:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: A human-readable error message.
detail:
type: string
description: Detailed information about the error.
example: example_value