8x8 Report Access API

openapi: 3.2.0
info:
  version: 4.1.0
  title: 8x8 Analytics for Contact Center Historical Metrics Report Access API
  contact:
    name: Analytics Team
    url: https://www.8x8.com/
    email: vcc-analytics@8x8.com
  termsOfService: https://www.8x8.com/terms-and-conditions
  x-logo:
    url: https://www.8x8.com/wp-content/uploads/2016/06/8x8-Logo-Tagline-bottom.png
  description: 'As a contact center supervisor, you may need to assess the performance of your agents.

    For example:

    - Analyze an agent’s call traffic queue

    - Drill down and analyze an agent’s activity history and get monthly, weekly, and hourly data

    - Determine the number of phone calls offered, accepted, rejected, or abandoned by an agent

    - Identify the total call handling time during the past hour


    The 8x8 Analytics for Contact Center Historic Metrics API offers an entire suite of historical reports for agent interactions, agent status, and queue interactions. The Historical Metrics API is an asynchronous API so it can be used to generate, view, and download a custom report from the Historical Reporting database.


    **Note**: The Historical Metrics API uses either the **v1**, **v2**, **v3**, **v4**, **v5**, **v6**, **v7** or **v8** path for the following URLs:

    ```

    https://api.8x8.com/analytics/cc/v1/historical-metrics/

    https://api.8x8.com/analytics/cc/v2/historical-metrics/

    https://api.8x8.com/analytics/cc/v3/historical-metrics/

    https://api.8x8.com/analytics/cc/v4/historical-metrics/

    https://api.8x8.com/analytics/cc/v5/historical-metrics/

    https://api.8x8.com/analytics/cc/v6/historical-metrics/

    https://api.8x8.com/analytics/cc/v7/historical-metrics/

    https://api.8x8.com/analytics/cc/v8/historical-metrics/

    ```


    _** For step-by-step instructions on using the Historical Metrics API refer to the [Historical Metrics Summary Guide ](doc:cc-historical-analytics-summary-report) or the [Historical Metrics Detailed Report Guide](doc:cc-historical-analytics-detailed-report)**_.

    ## **Authentication**

    You can try out this API through request authentication using your client credentials. Refer to [How to get API credentials](doc:how-to-get-api-keys) and [how to authenitcate](doc:oauth-authentication-for-8x8-xcaas-apis) for more information.


    All requests must be made over HTTPS - calls made over HTTP will fail.



    **Note**: The Historical Metrics API uses the **v1**, **v2**, **v3**, **v4**, **v5**, **v6**, **v7** or **v8** path for the following URL:


    - **`GET`** request: **`https://api.8x8.com/analytics/cc/{version}/historical-metrics/`**'
servers:
- description: Europe Historical Metrics API Production
  url: https://api.8x8.com/eu/analytics/cc/v8/historical-metrics
- description: APAC Historical Metrics API Production
  url: https://api.8x8.com/au/analytics/cc/v8/historical-metrics
- description: Canada Historical Metrics API Production
  url: https://api.8x8.com/ca/analytics/cc/v8/historical-metrics
- description: USA Historical Metrics API Production
  url: https://api.8x8.com/analytics/cc/v8/historical-metrics
tags:
- name: Report Access
  description: Create Reports, access report content and metadata
paths:
  /:
    post:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Create Report
      description: 'This endpoint initializes Report Access. For step-by-step instructions on using the Historical Metrics API refer to the [CC Historical Analytics Summary Report](/analytics/docs/cc-historical-analytics-summary-report) Guide. A report can be either defined as grouping, filtering, metrics, time interval, or another type.


        **Script Paths variant** (`type: script-paths`, v8+) uses a dedicated request shape (`ScriptPathsReportDefinitionRequest`). See [Script Paths Report](/analytics/docs/cc-historical-analytics-summary-report#9-script-paths-report) in the guide for its request shape, restrictions, and CSV output format.'
      operationId: cc-historical-report-create
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/ReportDefinitionRequest'
              - $ref: '#/components/schemas/ScriptPathsReportDefinitionRequest'
        description: Provides the report definition
        required: true
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfStatusResponse'
            application/xml;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfStatusResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /{id}:
    get:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Report Details
      description: This method provides information associated with a previously created report request. It includes all the parameters specified in the request. The value specified as {id} identifies which report request is displayed.
      operationId: cc-historical-report-details-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ReportDefinitionResponse'
            application/xml;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ReportDefinitionResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /{id}/status:
    get:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Report Status
      description: After a report is created, the status of the report can be checked periodically. The report can be either classified as IN_PROGRESS, DONE, or FAILED.
      operationId: cc-historical-report-status-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfStatusResponse'
            application/xml;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfStatusResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /{id}/data:
    get:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Report Data
      description: 'This method returns the actual report data. The returned report is paginated and the data is returned if the report has a DONE status. The report page size and numbering can be specified.


        **Not supported for `script-paths` reports** — such requests return **400 Bad Request**. Use `/{id}/download` instead.'
      operationId: cc-historical-report-data-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      - name: page
        in: query
        description: page
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: size
        in: query
        description: size
        required: false
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 1000
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfApiReportResponse'
            application/xml;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfApiReportResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /{id}/download:
    get:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Report Download
      description: 'This method returns report data as a downloadable file. Data can only be downloaded if the report has a DONE status. The first entry in the returned file specifies the names of the columns.


        For `script-paths` reports, the response is CSV only (XLSX is not supported). Columns: `Path ID`, `Parent Path ID`, `Script ID`, `Script Name`, `Node Type`, `Node Label`, `Depth`, `Count`, `Terminal`.'
      operationId: cc-historical-report-download-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Success/OK
          content:
            text/csv:
              schema:
                type: string
            application/vnd.ms-excel:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /{id}/links:
    get:
      security:
      - bearerAuth: []
      tags:
      - Report Access
      summary: Report Links
      description: 'This method returns all available links related to a previously created report. A link to the Report Status is always included in the return. If the status of the report is DONE, links to Report Data and Report Download are also included.


        For `script-paths` reports, only the Report Download link is included when status is `DONE` (no Report Data link).'
      operationId: cc-historical-report-links-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LinkItem'
            application/xml;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LinkItem'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /detailed-reports:
    post:
      tags:
      - Report Access
      summary: Create Detailed Report
      description: This endpoint initializes Detailed Report Access. For step-by-step instructions on using the Historical Metrics API refer to the [CC Historical Analytics Detailed Report](/analytics/docs/cc-historical-analytics-detailed-report) Guide. A report can be either defined as filtering, metrics, time interval, or another type.
      operationId: cc-detailed-report-create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DetailedReportDefinitionRequest'
        description: Provides the report definition
        required: true
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResourceOfStatusResponse'
            application/xml;charset=UTF-8:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResourceOfStatusResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
  /detailed-reports/{id}/data:
    get:
      tags:
      - Report Access
      summary: Detailed Report Data
      description: This method returns the actual detailed report data. The returned report is paginated and the data is returned if the report has a DONE status. The report page size and numbering can be specified.
      operationId: cc-detailed-report-data-by-id
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int64
      - name: size
        in: query
        description: size
        required: false
        schema:
          type: integer
          format: int32
          default: 100
          maximum: 1000
      - name: lastDocumentId
        in: query
        description: Must me omitted on initial request, required to get subsequent pages. The value can be found in the response header of each request.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success/OK
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfDetailedApiReportResponse'
            application/xml;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/ResourceOfDetailedApiReportResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not found
        '405':
          description: Method not allowed
        '406':
          description: Not acceptable
      deprecated: false
components:
  schemas:
    Filter:
      type: object
      properties:
        name:
          type: string
          example: agent
        values:
          type: array
          items:
            type: string
            example: ag319798
      title: Filter
    TotalItem:
      properties:
        type:
          type: string
          example: subtotal
        startIndex:
          type: integer
          example: 1
        endIndex:
          type: integer
          example: 5
      title: TotalItem
    DetailedRowItem:
      type: object
      properties:
        key:
          type: string
          example: startTime
        label:
          type: string
          example: Start Time
        value:
          type: object
          example:
            value: 2019-05-01T00:00+01:00
            ongoing: false
      title: DetailedRowItem
    Row:
      type: object
      properties:
        totals:
          $ref: '#/components/schemas/TotalItem'
        items:
          type: array
          items:
            $ref: '#/components/schemas/RowItem'
      title: Row
    RowItem:
      type: object
      properties:
        key:
          type: string
          example: startTime
        label:
          type: string
          example: Start Time
        value:
          type: string
          example: 2019-05-01T00:00+01:00
      title: RowItem
    ScriptPathsSearchQuery:
      type: object
      required:
      - field
      - operator
      - value
      properties:
        field:
          type: string
          enum:
          - script
          - queue
          - agent
          - channel
          example: agent
        operator:
          type: string
          enum:
          - in
          example: in
        value:
          type: array
          items:
            type: string
          example:
          - ag10000
          - ag7sfo_qfaTXCvwb7MsSUStw
      title: ScriptPathsSearchQuery
    DetailedRow:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/DetailedRowItem'
      title: DetailedRow
    DateRange:
      type: object
      required:
      - start
      - end
      properties:
        start:
          type: string
          format: date-time
          example: '2018-10-06T14:57:33.410Z'
        end:
          type: string
          format: date-time
          example: '2019-12-05T14:57:33.410Z'
      title: DateRange
    GroupBy:
      type: object
      required:
      - name
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
        name:
          type: string
          example: group-and-agent
      title: GroupBy
    DetailedReportDefinitionRequest:
      type: object
      required:
      - type
      - title
      properties:
        dateRange:
          $ref: '#/components/schemas/DateRange'
        intraDayTimeRange:
          $ref: '#/components/schemas/IntraDayTimeRange'
        metrics:
          type: array
          items:
            type: string
          example:
          - conferenceTime
          - conferencesEstablished
          - conferencesReceived
          - holdTime
        timezone:
          type: string
          example: Europe/Bucharest
        title:
          type: string
          example: Report for agent interactions
        type:
          type: string
          example: agent-interactions-call-summary
        searchQuery:
          type: array
          items:
            $ref: '#/components/schemas/SearchQuery'
        includeParticipants:
          type: boolean
          example: true
        reportSettings:
          $ref: '#/components/schemas/ReportSettings'
      title: DetailedReportDefinitionRequest
    ResourceOfDetailedApiReportResponse:
      type: array
      items:
        $ref: '#/components/schemas/DetailedRow'
      title: ResourceOfDetailedApiReportResponse
      xml:
        name: ResourceOfDetailedApiReportResponse
        attribute: false
        wrapped: false
    IntraDayTimeRange:
      type: object
      properties:
        start:
          type: string
          format: time
          example: '03:00:00.000'
        end:
          type: string
          format: time
          example: '21:00:00.000'
      title: IntraDayTimeRange
    ResourceOfStatusResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 64
        reason:
          type: string
        status:
          type: string
          example: IN_PROGRESS
      title: ResourceOfStatusResponse
      xml:
        name: ResourceOfStatusResponse
        attribute: false
        wrapped: false
    ScriptPathsReportDefinitionRequest:
      type: object
      required:
      - type
      - title
      - dateRange
      - timezone
      description: Request shape for the Script Paths report (v8+). Returns a hierarchical view of the paths taken by interactions through an IVR script, as a downloadable CSV. The request MUST NOT include `groupBy`, `granularity`, `metrics`, `includeSubTotal`, `includeGrandTotal`, or `includeParticipants`; requests that include these fields are rejected. Results are retrieved via `/{id}/download` only; the `/{id}/data` endpoint is not available for this type and returns `400 Bad Request`.
      properties:
        type:
          type: string
          enum:
          - script-paths
          example: script-paths
        title:
          type: string
          example: Script Paths Weekly Report
        dateRange:
          $ref: '#/components/schemas/DateRange'
        timezone:
          type: string
          example: Europe/Helsinki
        intraDayTimeRange:
          $ref: '#/components/schemas/IntraDayTimeRange'
        searchQuery:
          type: array
          description: Optional filters. Allowed `field` values are `script`, `queue`, `agent`, and `channel` (lowercase, case-sensitive). `operator` is `in`. `value` is an array of string IDs; see example.
          items:
            $ref: '#/components/schemas/ScriptPathsSearchQuery'
          example:
          - field: agent
            operator: in
            value:
            - agfDAzC5NtSRuHol5GA4RT6A
            - ag10000
            - ag7sfo_qfaTXCvwb7MsSUStw
          - field: channel
            operator: in
            value:
            - 1zkbCLd_R3ij4bC0T_hY7w
            - ZOLa_Q-DSlSpdfq--H9vPQ
            - ITPIhMTWQf-mpiQ_lahDQw
          - field: queue
            operator: in
            value:
            - '169'
            - '872'
          - field: script
            operator: in
            value:
            - '4163'
            - '5471'
      title: ScriptPathsReportDefinitionRequest
    SearchQuery:
      type: object
      properties:
        field:
          type: string
          example: queueName
        operator:
          type: string
          example: contains
        value:
          type: string
          example: Sales
      title: SearchQuery
    ReportDefinitionRequest:
      type: object
      required:
      - type
      - granularity
      - title
      properties:
        dateRange:
          $ref: '#/components/schemas/DateRange'
        intraDayTimeRange:
          $ref: '#/components/schemas/IntraDayTimeRange'
        granularity:
          type: string
          example: month
        groupBy:
          $ref: '#/components/schemas/GroupBy'
        metrics:
          type: array
          items:
            type: string
          example:
          - conferenceTime
          - conferencesEstablished
          - conferencesReceived
          - holdTime
        timezone:
          type: string
          example: Europe/Bucharest
        includeSubTotal:
          type: boolean
        includeGrandTotal:
          type: boolean
        title:
          type: string
          example: Report for agent interactions
        type:
          type: string
          example: agent-interactions-call-summary
      title: ReportDefinitionRequest
    LinkItem:
      type: object
      properties:
        link:
          type: string
          xml:
            name: link
            attribute: true
            wrapped: false
        relation:
          type: string
          xml:
            name: relation
            attribute: true
            wrapped: false
          example:
          - next
          - status
          - data
          - download
      title: LinkItem
    ReportSettings:
      type: object
      properties:
        showOngoingInteractions:
          type: boolean
          example: true
        showInteractionsStateInTime:
          type: boolean
          example: true
      title: ReportSettings
    ReportDefinitionResponse:
      type: object
      properties:
        id:
          type: string
          example: '123'
        status:
          type: string
          example: DONE
        dateRange:
          $ref: '#/components/schemas/DateRange'
        intraDayTimeRange:
          $ref: '#/components/schemas/IntraDayTimeRange'
        granularity:
          type: string
          example: month
        groupBy:
          $ref: '#/components/schemas/GroupBy'
        metrics:
          type: array
          items:
            type: string
          example:
          - conferenceTime
          - conferencesEstablished
          - conferencesReceived
          - holdTime
        timezone:
          type: string
          example: Europe/Bucharest
        includeSubTotal:
          type: boolean
        includeGrandTotal:
          type: boolean
        title:
          type: string
          example: Report for agent interactions
        type:
          type: string
          example: agent-interactions-call-summary
      title: ReportDefinitionResponse
    ResourceOfApiReportResponse:
      type: array
      items:
        $ref: '#/components/schemas/Row'
      title: ResourceOfApiReportResponse
      xml:
        name: ResourceOfApiReportResponse
        attribute: false
        wrapped: false
  securitySchemes:
    ApiKeyAuth:
      type: oauth2
      description: This API uses OAuth 2 with the client credentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: https://api.8x8.com/oauth/v2/token
          scopes:
            read: Grants read access
            write: Grants write access
            admin: Grants access to admin operations
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
x-readme:
  explorer-enabled: true
  proxy-enabled: true