CC Historical Analytics Summary Report

Access the Historical Analytics Summary reports with output in JSON, CSV or XLSX formats. This is a multi step process where a request is made, then a report is generated in the cloud and then the output can be downloaded

Customers looking to access data in JSON or CSV/XLSX from CC Historical Analytics can follow the this multi step process.

📘

You will need a working API key to begin

How to get API Keys

The base URL is region specific, based on the location of your Contact Center tenant.

  • United States: api.8x8.com/analytics/cc/{version}/historical-metrics/

  • Europe: api.8x8.com/eu/analytics/cc/{version}/historical-metrics/

  • Asia-Pacific: api.8x8.com/au/analytics/cc/{version}/historical-metrics/

  • Canada: api.8x8.com/ca/analytics/cc/{version}/historical-metrics/

  • {version} to be replaced by current Version. As of June 2023 this is 7 resulting in /v7/

1. Authenticate to retrieve access token

OAuth Authentication for 8x8 XCaaS APIs is used to get a temporary access_token for use in with this API

Outputs For Next Step:

  • access_token
  • expires_in

The following steps will use the access_token as a Bearer Token form of authentication. This takes the form of the
Authorization header being set to Bearer access_token (Space between Bearer and the access_token)

📘

JSON Examples shown, XML Also available

This guide shows all the examples in JSON. It is possible to retrieve responses in XML by specifying the following header

Accept: application/xml

2 Multitenancy support

If the API is used for a multitenant customer the requests should contain "X-Tenant-Info" header variable where needs to specify the desired tenantId. The "X-Tenant-Info" header is not mandatory in case of a single tenant customer.

The following error messages could be returned when dealing with a multitenant customer:

  • if for a multitenant customer request the "X-Tenant-Info" header is not provided the HTTP 400 code along with "Bad request: X-Tenant-Info header is missing." message will be returned
  • if a wrong tenantId is provided the HTTP 400 code along with "Bad request: Invalid value for X-Tenant-Info header." message will be returned

3. Get Available Report Types

CC Historical Analytics allows the consumer to get a listing of the available reports including information about their options and available data.

Additional information about each of the reports and detailed definitions of metrics can be found in the CC Historical Analytics Glossary

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-typeSpecific report type to get information on. Omit this parameter to get all report types.agent-status-by-status-code

API reference

Report Types Request

The definition of a single report can also be retrieved by adding the report-type to the path

curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/report-types' \
     --header 'Accept: application/json;charset=UTF-8' \
     --header 'Authorization: Bearer {access_token}'
curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/report-types/agent-status-by-status-code' \
     --header 'Accept: application/json;charset=UTF-8' \
     --header 'Authorization: Bearer {access_token}' 

Report Types Response

The response shows each report-type that's available.

📘

Detailed Reports

This returns some "detailed" report types as well as the summary reports. Detailed reports have a different format described in the CC Historical Analytics Detailed Report Guide

Outputs For Next Step:
For the summary reports the response has a number of elements to guide the usage:

  • type each report type has a unique definition
  • groupBy each report has one or more groupBy options. This specifies the grouping for the output
    • name this is the name to specify when creating a report with a specific grouping
    • filters these are the available filters for this report type for this particular grouping. The filters available vary depending on the type AND the grouping.
  • metrics these are the available metrics for the report type. When creating a report. See the CC Historical Analytics Glossary for additional detail on the definition of the available metrics
  • When running reports:
    • if no metrics are specified: All metrics will be returned
    • if metrics are specified: ONLY the specified metrics will be returned

The body will be an array as shown below.

  • The array will contain one or more objects as described here

    • type: this is the report type and name of the report
    • groupBy: array of options for grouping the report by various dimensions
      • name: name of the grouping
      • filters: array of the possible filtering options for this grouping for this report
    • value: array of the metrics available for this report
[
    {
        "type": "report type name",
        "groupBy": [
            {
                "name": "name of grouping 1",
                "filters": [
                    "filterable dimension 1",
                    "filterable dimension 2"
                ]
            },
            {
                "name": "name of grouping 2",
                "filters": [
                    "filterable dimension 1",
                    "filterable dimension 2",
                    "filterable dimension 3",
                ]
            }
        ],
        "metrics": [
            "report metric 1",
            "report metric 2"
        ]
    }
]

Sample Response for single report type

The result will be different for each report type.

{
    "type": "agent-interactions-summary",
    "groupBy": [
        {
            "name": "agent",
            "filters": [
                "agent"
            ]
        },
        {
            "name": "agent-and-media",
            "filters": [
                "agent",
                "media"
            ]
        },
        {
            "name": "agent-and-media-and-channel",
            "filters": [
                "agent",
                "media"
            ]
        },
        {
            "name": "agent-and-media-and-channel-and-queue",
            "filters": [
                "agent",
                "media",
                "queue"
            ]
        },
        {
            "name": "agent-and-media-and-queue",
            "filters": [
                "agent",
                "media",
                "queue"
            ]
        },
        {
            "name": "group",
            "filters": [
                "group"
            ]
        },
        {
            "name": "group-and-agent",
            "filters": [
                "agent",
                "group"
            ]
        },
        {
            "name": "group-and-agent-and-media",
            "filters": [
                "agent",
                "group",
                "media"
            ]
        },
        {
            "name": "group-and-agent-and-media-and-channel",
            "filters": [
                "agent",
                "group",
                "media"
            ]
        },
        {
            "name": "group-and-agent-and-media-and-channel-and-queue",
            "filters": [
                "agent",
                "group",
                "media",
                "queue"
            ]
        },
        {
            "name": "group-and-agent-and-media-and-queue",
            "filters": [
                "agent",
                "group",
                "media",
                "queue"
            ]
        },
        {
            "name": "group-and-media",
            "filters": [
                "group",
                "media"
            ]
        },
        {
            "name": "group-and-media-and-channel",
            "filters": [
                "group",
                "media"
            ]},
        {
            "name": "group-and-media-and-channel-and-queue",
            "filters": [
                "group",
                "media",
                "queue"
            ]
        },
        {
            "name": "group-and-media-and-queue",
            "filters": [
                "group",
                "media",
                "queue"
            ]
        }
    ],
    "metrics": [
        "abandoned",
        "abandonedPercentage",
        "accepted",
        "acceptedPercentage",
        "alerting",
        "avgBusyTime",
        "avgHandlingTime",
        "avgHoldTime",
        "avgSpeedToAnswer",
        "avgWrapUpTime",
        "blindTransferToAgent",
        "blindTransferToQueue",
        "blindTransfersInitiated",
        "blindTransfersReceived",
        "busyTime",
        "handlingTime",
        "hold",
        "holdTime",
        "longestHoldTime",
        "longestOfferingTime",
        "offeringTime",
        "presented",
        "rejectTimeout",
        "rejected",
        "rejectedPercentage",
        "transfersInitiated",
        "transfersInitiatedPercentage",
        "transfersReceived",
        "warmTransfersCompleted",
        "warmTransfersReceived",
        "wrapUpTime"
    ]
}

4. Creating A Summary Report

📘

This sample is applicable to ALL summary report types

The values in passed in will be specific to the report-type but the concepts are applicable to all summary report types.

Parameters

Method: POST

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap
Content-TypeSet Content-Type to application/jsonapplication/json

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-typeSpecific report type to get information on. Omit this parameter to get all report types.agent-status-by-status-code

Body

NameRequiredDescriptionExample
typeThe report type. Acceptable value is any one of the types returned from the report-types APIagent-status-by-status-code
titleThe report title, which allows only the characters listed below: letters from A to Z, a to z, 0 to 9, whitespaces or ! - _ . * ' ( ). If the report is later downloaded as a file, the title is used as the filename.Agent Status By Code Aug Sep
dateRange.startThis parameter specifies that only events and records on or after the specified date are in the report. The entered values should follow the ISO 8061 standard (YYYY-MM-DDTHH:MM:SS.SSSZ) (For example, 2019-09-01T23:00:00.000Z)
dateRange.endThis parameter specifies that only events and records on or before the specified date are included in the report. The entered values should follow the ISO 8061 standard. (YYYY-MM-DDTHH:MM:SS.SSSZ) (For example, 2019-09-01T23:00:00.000Z)
granularityThis parameter specifies how to aggregate the report data by time intervals. You must use one of the following values: 15m, 30m, hour, day, week, month, year, or none. See granularity for more information.15m
groupBy.nameThis parameter controls how your data should be grouped by dimensions. It must be one of the grouping options returned by report-type for the specified report type.media-and-channel-and-queue
groupBy,filters[]Filters are an array of names and values that describes the dimension to filter by and the values of those filter(s). See filters for more detail.filters
timezoneThe desired timezone (IANA Time Zones. Examples America/New_York, Europe/Helsinki Wikipedia Time Zone List) that is applicable to current metrics only. Accepted timezone values are those that are configured for the tenant. The value can be the tenant’s default timezone or a value defined as an optional timezone. If no value is specified, the tenant’s default timezone is usedEurope/Helsinki
intraDayTimeRange.startSee IntraDayTimeRange. The start time for the intraDayTimeRange. The format is hh:mm:ss08:30:00
intraDayTimeRange.endSee IntraDayTimeRange. The end time for the intraDayTimeRange. The end must be at least 15 minutes after the start. The format is hh:mm:ss17:00:00
metricsCan be omitted and all available metrics will be returned, or an array of metrics can be specified and only these metrics will be returned."metrics": [
"accepted",
"acceptedInSla",
"acceptedInSlaPercentage",
"acceptedPercentage",
"totalAbandoned",
"totalAbandonedPercentage"
]
includeSubTotal (Default false) This parameter adds subtotals rows in the report. It accepts only Boolean values written as true or false or as strings listed as "true" or "false".true
includeGrandTotal(Default false)This parameter puts the grand total row in the report. It accepts only Boolean values written as true or false or as strings listed as "true" or "false"true

granularity

This parameter specifies how to aggregate the report data by time intervals. You must use one of the following values: 15m, 30m, hour, day, week, month, year, or none.

  • If the assigned parameter value is none, then the report data is not aggregated by time.

  • For date range intervals less than or equal to a week the accepted > - granularities are 15m, 30m, hour, day, or none.

  • For date range intervals less than or equal to a month and but longer than a week the accepted granularities are none, hour, day, or week

  • For date range intervals longer than a month the accepted granularities are none, month, or year

intraDayTimeRange

This parameter is used to specify a time range filter which applies within each day of the report. If this parameter is not specified, data will be returned for the complete time frame described in the mandatory dateRange object.

🚧

intraDayTimeRange minimum size

The end must be 15 minutes after the start for summary reports and 5 minutes after the start for detailed reports.

  • start: the start time for the intraDayTimeRange. The format is hh:mm:ss
  • end: the end time for the intraDayTimeRange. The format is hh:mm:ss

If the requirement is to only see data between 8:30am and 5pm on each day the intraDayTimeRange would be passed as follows

"intraDayTimeRange": 
{
        "start": "08:30:00",
        "end": "17:00:00"
}

In version 6 intraDayTimeRange was enhanced to to cover cross-day time range filtering in reports allowing to generate a single report for overnight shifts, and it is available for all aggregated and detailed report types. You can now generate reports for overnight shifts of specific time ranges that cross two days.

With the following example can be generated a report which cover activities for a week but for only time intervals from 20:00 to 06:00 time range.

"dateRange":
{ 
    "start": "2022-08-05T00:00:00.00Z", 
    "end": "2022-08-11T00:00:00.00Z" 
},
"intraDayTimeRange": 
{
    "start": "20:00:00",
    "end": "06:00:00"
}

filters

Parameter can be completely omitted Or an empty array can be passed for no filtering.

For example report type queue-interactions-summary and groupBy media-and-channel-and-queue we can chose to not filter at all OR filter by media and or queue

Each report type has it's own filtering capabilies which can be found in the Report Types Response each groupBy has it's own applicable filters.

  "filters": [
  ] 
  "filters": [
       {
          "name": "queue",  
          "values": ["103"]
       }
  ]
  "filters": [
       {
          "name": "queue",  
          "values": ["103", "330"]
       }
  ]
  "filters": [
       {
          "name": "queue",  
          "values": ["103", "330"]
       },
       {
          "name": "media",  
          "values": ["Phone", "Chat"]
       }
  ]

metrics

If the requirement is to only have a subset of the the available metrics for the report type, we specify the required metrics

  • if no metrics are specified (omitted entirely or empty array) ==> All metrics will be returned
  • if metrics are specified ==> ONLY the specified metrics will be returned

CC Historical Analytics Glossary provides detail on the definition of the available metrics

"metrics": [
    "accepted",
    "acceptedInSla",
    "acceptedInSlaPercentage",
    "acceptedPercentage",
    "totalAbandoned",
    "totalAbandonedPercentage"
]

API reference

Create Report Request

In this example we are running the report from 3rd August to 2nd September, we are only interested in the periods between 8:30am and 5pm on each day and we are grouping the data by media, channel and queue at a weekly granularity.
The data returned will only be for queue id is 103 and 330 and only if the media is Phone or Chat and the metrics returned will be only the ones specified, with sub and grand totals.

curl --location --request POST 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "type": "queue-interactions-summary",
    "title": "Weeky Queue Report for OPS",
    "dateRange": {
        "start": "2022-08-03T00:00:00.000Z",
        "end": "2022-09-02T00:00:00.000Z"
    },
    "granularity": "week", 
    "groupBy":{
    	"name":"media-and-channel-and-queue",
         "filters": [
             {
                "name": "queue",  
                "values": ["103", "330"]
             },
             {
                "name": "media",  
                "values": ["Phone", "Chat"]
             }
        ]
    },
    "timezone": "America/New_York",
    "intraDayTimeRange":
    {
            "start": "08:30:00",
            "end": "17:00:00"
    },
    "metrics": [
        "accepted",
        "acceptedInSla",
        "acceptedInSlaPercentage",
        "acceptedPercentage",
        "totalAbandoned",
        "totalAbandonedPercentage"
    ],
    "includeGrandTotal": true,
    "includeSubTotal": true
}'

Create Report Response

For an accepted request to create a report the response will be 200 OK

Headers

  • Link => The Link header will provide details on how to check the status of the create request
<https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710192/status; rel="status">

Body

  • id: this is the identifier for the generated report
  • status: this is the status of the request to create the report
    • IN_PROGRESS : the report is being generated, usually the initial status
    • DONE : the report has been generated
    • FAILED : the report has failed to generate
{
    "id": 2710192,
    "status": "IN_PROGRESS"
}

5. Get Report Status

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-idreport id returned in the create report request.2710192

API reference

Report Status Request

curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710192/status' \
     --header 'Authorization: Bearer access_token'

Report Status response

This will be the same format as the response from creating the report. Recheck the status periodically until the status is "DONE".

🚧

Don't check status in a tight loop (please)

Leave some time between status checks, repeatedly requesting updates without taking a pause is more likely to slow the response than speed it up.

Headers

The Link header WILL ONLY be present if the report staus is "DONE"

  • Link => The Link header will provide details on how access the data and download for the report
<https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710663/data?page=0&size=100>; rel="data",
<https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710663/download>; rel="download"

Body

  • id: this is the identifier for the generated report
  • status: this is the status of the request to create the report
    • IN_PROGRESS : the report is being generated, usually the initial status
    • DONE : the report has been generated
    • FAILED : the report has failed to generate
{
    "id": 2710192,
    "status": "IN_PROGRESS"
}

6a. Get Report Data (JSON)

📘

Accessing the report Data

The data is available via JSON or via CSV/XLSX. To access the data as JSON the data endpoint is used, for CSV/XLSX the download endpoint is used.

🚧

Data (JSON) results are capped at 10,000 records.

CSV/XLS will return all larger result sets.

Detailed Reports have an alternative approach since larger result sets are expected.

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-idreport id returned in the create report request.2710192

Query

NameRequiredDescriptionExample
page(starts from 0) enables navigation to the expected page; if no value is specified then the first page is retrieved. Required on subsequent pages0
sizegives the amounts of elements on one page. If no value is specified then default values are used (0 for page, 100 for size). Maximum page size is 1000 elements200

API reference

Report Data (JSON) Request

curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710192/data?page=0&size=100' \
--header 'Authorization: Bearer {access_token}'

Report Data (JSON) Response

Headers

  • Link => The Link header will provide a link to the next page in the data if there are additional pages. Will not be present if there are no more pages.
<https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710663/data?page=1&size=100>; rel="next"
  • X-Page: current page number, 0(zero) is the first page
  • X-Page-Size: size of the requested pages
  • X-Total-Pages: total number of pages for the report, 1 if only one page.
  • X-Total-Elements: total number of elements for the report

Body

The body will be an array as shown below.

  • The array could be empty if there are no records in the result

  • If not empty the array will contain one or more objects as described here
    - total: if this represents a subtotal or grandtotal (only present if "includeGrandTotal": true, "includeSubTotal": true were requested)
    - items: array of the dimensions and metrics being returned. There will be one object for each.
    - key: the value will be the name of the dimension/metric
    - label: the value will be the human friendly name of the dimension/metric
    - value: the value will be the value of the dimension/metric. This is ALWAYS a string.

    ```json
    [
        {
            "total": null,
            "items": [
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                },
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                }
            ]
        },
        {
            "total": {
                "type": "subtotal",
                "startIndex": 0,
                "endIndex": 1
            },
            "items": [
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                },
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                }
            ]
        }
        ,
        {
            "total": {
                "type": "grandtotal",
                "startIndex": null,
                "endIndex": null
            },
            "items": [
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                },
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                }
            ]
        }
    ]
    ```
    ```json
    [
        {
            "total": null,
            "items": {
                "name1": "value1",
                "name2": 3
                "name3": "2022-09-02T00:00:00.000Z",
            }
            
        },
        {
            "total": {
                "type": "subtotal",
                "startIndex": 0,
                "endIndex": 1
            },
            "items": [
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                },
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                }
            ]
        }
        ,
        {
            "total": {
                "type": "grandtotal",
                "startIndex": null,
                "endIndex": null
            },
            "items": [
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                },
                {
                    "key": "name of key",
                    "label": "Human friendly label of key",
                    "value": "string representation of value",
                }
            ]
        }
    ]
    ```
    

🚧

Dimension values for subtotal and grandtotal items

Where a subtotal or grandtotal is summarizing multiple instances of a single dimension the value for that item will be null since there is no single correct value

{
    "total": {
        "type": "subtotal",
        "startIndex": 23,
        "endIndex": 23
    },
    "items": [
        {
            "key": "startTime",
            "label": "Start Time",
            "value": "2022-08-29T00:00-04:00"
        },
        {
            "key": "endTime",
            "label": "End Time",
            "value": "2022-09-05T00:00-04:00"
        },
        {
            "key": "media",
            "label": "Media",
            "value": "Phone"
        },
        {
            "key": "channel",
            "label": "Channel",
            "value": null
        },
        {
            "key": "queue",
            "label": "Queue",
            "value": null
        },
        {
            "key": "queueId",
            "label": "Queue Id",
            "value": null
        },
        {
            "key": "accepted",
            "label": "Accepted",
            "value": "0"
        }
    ]
}

6b. Get Report Download (CSV/XLSX)

📘

Accessing the report Data

The data is available via JSON or via CSV/XLSX. To access the data as JSON the data endpoint is used, for CSV/XLSX the download endpoint is used.

📘

There is no pagination the whole file will be returned.

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap
AcceptSpecify the download type
- CSV text/csv
- XLSX text/xlsx
text\xlsx

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-idreport id returned in the create report request.2710192

API reference

Report Download (CSV/XLSX) Request

curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710192/download' \
--header 'Accept: text/xlsx' \
--header 'Authorization: Bearer {access_token}'

Report Download (CSV/XLSX) Response

Headers

  • Content-Disposition => will contain information about the file generated, the filename will reflect the title input in the report creation with the xlsx or csv type extension added.
    Example: attachment; filename="Weeky Queue Report for OPS.xlsx"

Body

The file content is returned in the body.

7. Access Report Links

Parameters

Method: GET

Headers

NameRequiredDescriptionExample
AuthorizationPass the access_token returned from the authentication request as a Bearer token Bearer {access_token}Bearer kfjdfi3jfopajdkf93fa9pjfdoiap

Path

NameRequiredDescriptionExample
versionThe current version is v<<versionCCAHistorical>>v7
report-idreport id returned in the create report request.2710192

API reference

Report Links Request

curl --location --request GET 'https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2710192/links' \
--header 'Authorization: Bearer {access_token}'

Report Links Response

Body

The body will be an array as shown below.

  • status is always shown
  • data and download are shown if the report status is DONE
[
    {
        "relation": "status",
        "link": "https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2684392/status"
    },
    {
        "relation": "data",
        "link": "https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2684392/data?page=0&size=100"
    },
    {
        "relation": "download",
        "link": "https://api.8x8.com/analytics/cc/v<<versionCCAHistorical>>/historical-metrics/2684392/download"
    }
]