1. Intelligent Advisor REST APIREST API for Intelligent Advisor 24B
  2. Use Cases
  3. Using the Statistics REST API

Using the Statistics REST API

The Statistics REST API provides the ability to retrieve statistics data. The query parameters and resulting data is equivalent to the metrics in Intelligent Advisor Hub.

  • Statistics with a series of "deploymentSeries" are equivalent to the site-wide statistics shown on the right-hand side the Deployments page in Intelligent Advisor Hub.

  • Statistics with a series of "deploymentVersionSeries" are equivalent to the deployment-specific statistics shown on the right-hand side the deployment details page in Intelligent Advisor Hub.

Example GET Statistics

This operation will get an empty statistics response only containing related links.

The GET request URL looks like:

opa-hub/api/12.2.23/statistics

The response to a get statistics request looks like the following:

{
    "items": [
    ],
    "links": [
        {
            "rel": "canonical",
            "href": "https://mysite.example.com/opa-hub/api/12.2.23/statistics/deployments"
        },
        {
            "rel": "parent",
            "href": "https://mysite.example.com/opa-hub/api/12.2.23/statistics"
        },
        {
            "rel": "describedBy",
            "href": "https://mysite.example.com/opa-hub/api/12.2.23/metadata-catalog/statistics/deployments"
        },
        {
            "rel": "related",
            "href": "https://mysite.example.com/opa-hub/api/12.2.23/deployments/{items[*].deploymentSeries[*]}",
            "templated": true
        },
        {
            "rel": "related",
            "href": " https://mysite.example.com/opa-hub/api/12.2.23/deployments/{items[*].deploymentVersionSeries[*].deploymentName}/versions/{items[*].deploymentVersionSeries[*].deploymentVersion}",
            "templated": true
        }
    ]
}

The "related" link in the links array indicates where deployment names are located.

Note that the "templated" property indicates that the HREF is templated. The expressions inside curly braces indicate the parameters inside the request can be substituted into a request URL.

Example POST Site-Wide Statistics

This operation will retrieve statistics for the given definition.

The POST request URL looks like:

opa-hub/api/12.2.23/statistics

The basic structure expected for the POST request for the statistics resource is as follows for site-wide statistics:

{
    "metric": "deploymentSessionsByDate",
    "deploymentSeries": [
        "Example Project 1",
        "Example Project 2"
    ],
    "timePeriod": "last30Days",
    "groupBy": "day",
    "includedActionTypes": [
        "agentInterviews", "nonAgentInterviews"
    ]
}

Series expressions can be any of the following:

Series Valid Expressions
deploymentSeries 
"all"
deploymentSeries 
[ "deployment name" ]
deploymentSeries 
[ "deployment name 1", "deployment name 2" ... ]

The response will consist of an object containing an array of data containing the statistics:

{
    "chartTitle": "Sessions by date",
    "dataTypeTitle": "Sessions by date",
    "valueTitle": "Number of sessions created",
    "categoryTitle": "Date",
    "includedActionTypes": [
       "agentInterviews",
       "nonAgentInterviews"
    ],
    "data": [
      {
        "value": 0,
        "series": "Example Project 1",
        "category": "2021-02-01"
      },
      {
        "value": 0,
        "series": "Example Project 1",
        "category": "2021-02-02"
      },
      {
        "value": 0,
        "series": "Example Project 1",
        "category": "2021-02-03"
      },
      ... ,
      {
        "value": 0,
        "series": "Example Project 2",
        "category": "2021-02-01"
      },
      {
        "value": 0,
        "series": "Example Project 2",
        "category": "2021-02-02"
      },
      {
        "value": 0,
        "series": "Example Project 2",
        "category": "2021-02-03"
      },
      ...
    ]
}

The following POST could be used to request multiple statistics series:

{
    "items": [
        {
            "metric": "interviewsByLength",
            "deploymentSeries": "all",
            "timePeriod": "last30Days"
        },
        {
            "metric":"interviewsByDuration",
            "deploymentSeries": "all",
            "timePeriod":"last30Days"
        }
    ]
}

The response would consist of two items, where each item contains the requested statistics:

{
    "items": [
    {
        "chartTitle": "Interviews by length",
        "metricTitle": "Interviews by length",
        "valueTitle": "Percentage of Sessions",
        "categoryTitle": "Screens Visited",
        ...
        "data": [
            ...
        ]
    },
    {
        "chartTitle": "Interviews by duration",
        "metricTitle": "Interviews by duration",
        "valueTitle": "Percentage of Sessions",
        "categoryTitle": "Duration (Minutes)",
        ...
        "data": [
            ...
        ]
    }
  ]
}

Example POST Deployment-Specific Statistics

This operation will retrieve statistics for the given definition.

The POST request URL looks like:

opa-hub/api/12.2.23/statistics

The basic structure expected for the POST request for the statistics resource is as follows for deployment-specific statistics:

{
    "metric": "interviewsByScreenDuration",
    "deploymentVersionSeries": [
        {
            "deploymentName": "Example Project 1",
            "deploymentState": "active"
        }
    ],
    "timePeriod": "limitToLast30Days",
    "groupBy": "day",
    "includedActionTypes": [
        "nonAgentInterviews"
    ]
}

Series expressions can be any of the following:

Series Valid Expressions
deploymentVersionSeries 
[
    {
        "deploymentName": "deployment name",
        "deploymentState": "all"
    }
]
deploymentVersionSeries 
[
    {
        "deploymentName": "deployment name",
        "deploymentState": "active"
    },
    {
        "deploymentName": "deployment name",
        "deploymentVersion": 1
    }
]

The response will consist of an object containing an array of data containing the statistics:

{
    "chartTitle": "Interview screens by time spent",
    "dataTypeTitle": "Interview screens by time spent",
    "valueTitle": "Average Time per Session (seconds)",
    "categoryTitle": "Interview Screen",
    "includedActionTypes": [
        "nonAgentInterviews"
    ],
    "data": [
        {
            "value": 16.298,
            "series": "Example Project 1:Active",
            "category": "1: Create things"
        },
        {
            "value": 10.9915,
            "series": "Example Project 1:Active",
            "category": "2: Create a box and select a filtered thing"
        },
        {
            "value": 6.5735,
            "series": "Example Project 1:Active",
            "category": "3: Create a box and select a thing"
        },
        {
            "value": 49.5725,
            "series": "Example Project 1:Active",
            "category": "4: Select a thing from Global - filtered by rules"
        },
        {
            "value": 932.176,
            "series": "Example Project 1:Active",
            "category": "5: Create a box and select a thing"
        },
        {
            "value": 0,
            "series": "Example Project 1:Active",
            "category": "6: Select a thing for the box"
        },
        {
            "value": 0,
            "series": "Example Project 1:Active",
            "category": "7: Interview Complete"
        },
        {
            "value": 9.589,
            "series": "Example Project 1:Active",
            "category": "8: the box"
        }
    ]
}

Combinations of Parameters

The following combination of parameters are allowed:

Metric Series Time Period Group By Included Action Types
assessmentRateByDate deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years month, day, hour answerServiceAPICalls, assessServiceAPICalls, batchAssessCases, referencedDecisionServiceCases
deploymentAgentsByDate deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years month, day, hour (none)
deploymentAssessmentsByDate deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years month, day, hour answerServiceAPICalls, assessServiceAPICalls, batchAssessCases, referencedDecisionServiceCases
deploymentInteractionByDate deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years month, day, hour agentInterviews, nonAgentInterviews, allAssessedCases
deploymentSessionsByDate deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years month, day, hour agentInterviews, nonAgentInterviews
interviewsByDuration deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years minute agentInterviews, nonAgentInterviews
interviewsByLength deploymentSeries deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years screenVisit agentInterviews, nonAgentInterviews
interviewsByScreenDuration deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years screenName agentInterviews, nonAgentInterviews
interviewsByScreenState deploymentVersionSeries last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days, last1Year, last2Years screenName agentInterviews, nonAgentInterviews

The following time period and grouping combinations are prohibited:

Time Period Group By Reason
last1Year, last2Years hour Too many results. Can result in out-of-memory.
last24Hours, last48Hours, last72Hours, last7Days, last14Days, last30Days month Grouping is too coarse. Use day or hour instead.

Default Values

When no value is supplied, the following default values are supplied for the given metric:

Metric Time Period Group By Included Action Types
assessmentRateByDate last24Hours hour (day if time period is last1Year or last2Years) answerServiceAPICalls, assessServiceAPICalls, batchAssessCases, referencedDecisionServiceCases
deploymentAgentsByDate last24Hours hour (day if time period is last1Year or last2Years) (none)
deploymentAssessmentsByDate last24Hours hour (day if time period is last1Year or last2Years) answerServiceAPICalls, assessServiceAPICalls, batchAssessCases, referencedDecisionServiceCases
deploymentInteractionByDate last24Hours hour (day if time period is last1Year or last2Years) agentInterviews, nonAgentInterviews, allAssessedCases
deploymentSessionsByDate last24Hours hour (day if time period is last1Year or last2Years) agentInterviews, nonAgentInterviews
interviewsByDuration last24Hours minute agentInterviews, nonAgentInterviews
interviewsByLength last24Hours screenVisit agentInterviews, nonAgentInterviews
interviewsByScreenDuration last24Hours screenName agentInterviews, nonAgentInterviews
interviewsByScreenState last24Hours screenName agentInterviews, nonAgentInterviews