openapi: 3.0.0
info:
  title: API Stats
  description: The API Stats endpoints provide analytics on configured API call counts for your application. This suite enables multi-dimensional analysis of API usage with customizable grouping by date, platform, bundle, country, app version, device type, and API name.
  contact: {}
  version: 1.0.0
servers:
  - url: https://apptics.zoho.com/cx/api/v1
    description: API Endpoint
tags:
  - name: api-stats
    description: API Stats Module
paths:
  /api/multigroup:
    get:
      tags:
        - api-stats
      summary: Get API count by group
      description: Retrieves configured API call counts for a given date range with customizable grouping and aggregation. The grouping system supports combining up to two grouping entities such as date, platform, bundle, country, app version, device type, and API name. The response format is controlled by the <b>responseformat</b> parameter — use <code>nestedjson</code> for hierarchical output or <code>csvjson</code> for flat output. The response structure dynamically adapts to match the specified grouping configuration.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - $ref: '#/components/parameters/startdate'
        - $ref: '#/components/parameters/enddate'
        - $ref: '#/components/parameters/responseformat'
        - $ref: '#/components/parameters/group'
        - $ref: '#/components/parameters/apiname'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/api-multigroup-response'
              examples:
                group_date_platform:
                  summary: Response for group=date,platform
                  value:
                    result:
                      iOS:
                        01-07-2024: 22
                        02-07-2024: 9
                        03-07-2024: 97
                      Android:
                        01-07-2024: 69
                        02-07-2024: 222
                        03-07-2024: 20
                    status: 200
                group_appversion:
                  summary: Response for group=appversion
                  value:
                    result:
                      2.1.0: 548
                      2.0.5: 181
                      1.9.3: 33
                    status: 200
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
components:
  parameters:
    zsoid:
      name: zsoid
      description: Portal ID
      in: header
      required: true
      schema:
        type: string
      example: '10234695'
    projectid:
      name: projectid
      description: Project ID
      in: header
      required: true
      schema:
        type: string
      example: '12345689'
    startdate:
      name: startdate
      description: 'Beginning of date range for data retrieval. Required format: dd-MM-yyyy.'
      in: query
      required: true
      schema:
        type: string
      example: 01-07-2024
    enddate:
      name: enddate
      description: 'End of date range for data retrieval. Required format: dd-MM-yyyy.'
      in: query
      required: true
      schema:
        type: string
      example: 31-07-2024
    responseformat:
      name: responseformat
      description: Format of the response data. Use <code>nestedjson</code> for hierarchical output or <code>csvjson</code> for flat output.
      in: query
      required: true
      schema:
        type: string
        enum:
          - csvjson
          - nestedjson
      example: nestedjson
    group:
      name: group
      description: 'Comma-separated list of grouping entities. Allowed values: date, platform, bundle, country, appversion, devicetype, api. Minimum 1, maximum 2 groups. Response structure follows the specified group order in nested JSON format.'
      in: query
      required: true
      schema:
        type: string
      example: date,platform
    apiname:
      name: apiname
      description: Filter results by a specific API name.
      in: query
      required: false
      schema:
        type: string
      example: getUserProfile
    limit:
      name: limit
      description: 'Number of results per page. Default and maximum: 500.'
      in: query
      required: false
      schema:
        type: integer
      example: 100
    offset:
      name: offset
      description: 'Starting position for result pagination (default: 0). Increment by limit value for next page.'
      in: query
      required: false
      schema:
        type: integer
      example: 0
  schemas:
    api-multigroup-response:
      type: object
      properties:
        result:
          type: object
          description: Dynamically structured object based on the specified grouping configuration. Keys at each level correspond to the grouped dimension values; leaf values are API call counts.
          additionalProperties: {}
        status:
          type: integer
          example: 200
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            JProxy.jmobileapi.ALL: Analytics & Insight view
