ServiceNow Aggregate Statistics API

openapi: 3.1.0
info:
  title: ServiceNow Contact Aggregate Statistics API
  description: 'The Contact API provides endpoints that enable you to retrieve and update Customer Service Management (CSM) contact records.


    In addition, you can generate new social media profile records when creating a contact.


    The Contact API requires the Customer Service plugin (com.sn_customerservice) and is provided within the now namespace.


    **Authentication**: Users need the `csm_ws_integration` role for full API access.

    '
  version: Zurich
  contact:
    name: ServiceNow
    url: https://docs.servicenow.com
  x-namespace: now
servers:
- url: https://{instance}.servicenow.com/api/now
  description: ServiceNow instance
  variables:
    instance:
      default: instance
      description: Your ServiceNow instance name
security:
- basicAuth: []
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. User must have the csm_ws_integration role.