ServiceNow Aggregate Statistics API

openapi: 3.2.0
info:
  title: ServiceNow Aggregate Aggregate Statistics 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
servers:
- url: https://{instance}.service-now.com/api/now
  description: ServiceNow Instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
- oauth2: []
tags:
- name: Aggregate Statistics
  description: Operations for computing aggregate statistics on ServiceNow table records including count, sum, average, minimum, and maximum values.
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:
  schemas:
    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
    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: []
  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
  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: {}
externalDocs:
  description: ServiceNow Aggregate API Documentation
  url: https://www.servicenow.com/docs/bundle/yokohama-api-reference/page/integrate/inbound-rest/concept/c_AggregateAPI.html