OCP® Real-Time Metrics API
Real-Time Metrics
Real-time metrics show necessary information about the current status of an Omilia Application. They are created from a specific selection of Omilia KPIs, targeted to ensure the user is informed about the current state of their system, without being overwhelmed with information. These metrics will be publicly available through the Metrics API.
OCP® Analytics APIs
Metrics API
Metrics API is organized around HTTP REST. Our API currently offers two endpoints to serve parametrized and daily metric requests and uses HTTP response codes to indicate API errors.
Endpoint 1
Daily requests fetch the data from midnight of the day the request is made to the moment the request is filled.Endpoint 2
Hourly metrics, for which requests are filled using a call to a non-daily endpoint with a specific start/end time.
The highest granularity of metrics will be five minutes, which is also the default, but with the downsampling parameter, the user can apply a custom sampling rate. For example, request hourly metrics for the last 24 hours.
Authentication
Authenticate by including your secret API key in all requests. Your API keys carry many privileges, so be sure to keep them secret! Do not share this data in publicly accessible areas such as Github, client-side code, and so forth.
There are two types of API keys, depending on the privileges they carry:
admin
API keys - authorized to fully manage and query OCP resources, i.e. create, update, delete and list resourcesapplication
API keys - authorized to only query the OCP resource that they belong to
admin
API keys are provided by Omilia and application
API keys are generated when creating the respective resource
Include the desired API key in the HTTP Authorization header using the following authorization scheme.
Sample request:
curl -v -X GET {service_url} \
-H "Authorization: Token {api_key}" \
-H "Content-Type:application/json"
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Errors
The API provides a generic error response for every endpoint in the following format:
{
"error": <true|false>,
"code": <error_code>,
"message": "some message pointing to a specific erroneous situation"
}
Omilia uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (for example, a required parameter was omitted, and so on), and codes in the 5xx range indicate an error with Omilia’s servers.
However, not all errors map cleanly onto HTTP response codes. To understand the source of the error please refer to the list of codes in the documentation.
The Omilia API uses the following error codes:
HTTP Error Codes
Error Code | Meaning |
---|---|
200 | OK Everything worked as expected |
400 | Bad Request The request was unacceptable, often due to missing or invalid parameters |
401 | Unauthorized Invalid API key provided |
403 | Forbidden The provided API key is not authorized to access this resource |
404 | Not Found The requested resource doesn’t exist |
409 | Conflict The request conflicts with another request |
429 | Too Many Requests Too many requests sent to the API in a specific timeframe |
500, 502, 503, 504 | Server Errors Something went wrong on Omilia’s servers |
Metrics types
There are two types of metrics that will be supported:
Real-time metrics, are generated in real-time and are broken down into five-minute intervals. Available in Version 1.
Non-real-time metrics, (or batch metrics), which are exported from DWH. Those metrics are already offered in Convo Insights. Will be available in future versions of Metrics API.
The metrics will be available through two different endpoints. Version 1 will include the endpoint for real-time metrics only.
Real-Time and Non-Real-Time Metrics
The highest granularity of real-time metrics will be in five-minute intervals. For example, the end user will be able to see the number of invocations between 10:00-10:05, 10:05-10:10, and so on. On the other hand, non-real-time metrics (or batch metrics) will be aggregated on an hourly basis, the same as existing Convo Insights Solutions. For example, the user will be able to view total invocations between 10:00-11:00 and then 11:00-12:00. Both of these metrics will be able to be aggregated on a higher level.
Meaning for real-time and non-real-time metrics the end user will be able to fetch total invocations over the last two hours. Some discrepancy between real-time and batch metrics is expected. One reason is due to real-time metrics having a five minutes watermark after the dialog ended. In some cases, that data delay longer than that mark, and those dialogs won’t be taken into account for real-time reporting. On the other hand, batch metrics take longer to produce in order to retrieve data, even if they were sent with some delay, ensuring their accuracy. A simple example of a data sequence will be available.
Path Parameters
Property | Type | Required | Description |
---|---|---|---|
| string | Yes | The group (organization) the metrics requested belong to. Possible values: ocp |
| string | Yes | The type of metric requested. Possible values: batch, realtime |
Query Payload Fields
Property | Type | Required | Description |
---|---|---|---|
| array(string) | Yes | List of metrics requested. Available metrics of version 1 can be found in the following section |
| string | Yes | Query start date. This field value is limited by Supported date formats:
Possible values:
|
| string | No | Query end date Supported date formats:
Possible values:
|
| array(string) | No | List of miniapp names for the metrics requested. Possible values:
|
| array(string) | No | List of miniappTypes for the metrics requested. Possible values:
|
| array(string | No | Filter locale for metrics requested. Possible values:
Default value: If absent, will aggregate all locales for metrics requested. |
| array(string) | No | Filter channel for metrics requested. Possible values:
|
| boolean | No | Filter test flag for metrics requested. Possible values:
|
| boolean | No | Apply downsampling using interval and algorithm. Possible values:
|
| string | No | Possible values:
Default timezone: UTC |
Metrics API Example
Request
POST /metrics-api/{group}/{metric-type}/daily-miniapp-query
Response
{
"metrics":["error_tasks_batch"],
"filters": {
"miniappName":["car_retail_test"],
"miniappType":["CarRetail"],
"locale": "en-US"
},
"drilldown": "true",
"timezone": "timezone"
}
List of Real-Time Metrics
This set of near real-time metrics will be available in Metrics API v1.0. Apart from the description, there is a list of metrics parameters, also listed above, the user can use to aggregate, drill in, and out of.
Name | Description | Supported Filters (Query Parameters) | Unsupported Filters |
---|---|---|---|
| Total number of sessions the application received. Sessions refer to either unique IVR Calls or Chat Sessions (depending on the application), no matter how many miniApps or even Orchestrator flows were triggered. A session is counted when the first miniApp is triggered within OCP®. The sessions are recounted for each five-minute interval while they are still active. |
|
Note: |
| Total number of dialogs per Orchestrator root application. A dialog is a unique conversation (or call for IVR) within an application. This metric will be counted when Orchestrator root application is completed. |
Note: For Dialog metrics, | |
| Total number of dialogs per Orchestrator application that got transferred. This metric will be counted when Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only. |
Note: For Dialog metrics, | |
| Total number of dialogs per Orchestrator application that got terminated. This metric will be counted when the Orchestrator root application is completed in order to retrieve the End Type and is applicable to IVR applications only. |
Note: For Dialog metrics, | |
| The number of total invocations of each miniApp a flow/application or standalone The miniApp is counted upon completion of this task. |
| |
| The number of total successful invocations of each miniApp within a flow/application or standalone. The miniApp has Result:success.The miniApp has to be completed in order for us to know if it was successful. |
| |
| Total number of invocations per miniApp that ended with a system error, critical error or timeout error. |
| |
| Total |
| |
| Total |
| |
| Number of |
|
Time Series Example
The following example will help the end user understand how a Production Call with multiple steps and miniApps would be depicted in real-time metrics. We have a Banking IVR Application, built using Orchestrator. The main flow consists of a sequence of three miniApps. A call enters our IVR at 10:01 and exits the IVR at 10:08. During this call three miniApps are used:
miniApp 1 is triggered the moment the call reaches the application,
miniApp 2 is triggered at 10:02 after miniApp 1 is completed,
miniApp 3 is triggered from 10:06 until 10:08 when the call is terminated.

Real-Time Metrics Intervals
Real-time metrics are split into five-minute intervals. For this example the call will be active for the following two intervals:
A: 10:00- 10:05
In the Insights graph it will be marked as Time Point: 10:05B: 10:05-10:10
In the Insights graph it will be marked as Time Point: 10:10
Metrics Outputs
miniApp1 Invocation will be added at time frame A after 10:02
miniApp2 Invocation will be added at time frame A after 10:06
miniApp3 Invocation will be added at time frame B after 10:08
This session initiated will be added at time frame A after 10:02
This Application/Dialog will be added at time frame A after 10:08
If this call is transferred out from IVR will be added in Dialogs Transferred at time frame A after 10:08
If miniApp2 has three steps with
noMatches
, they will be added in time frame A, sequentially, meaning the counter could be increasing as more matches are occurring for the same miniApp.If miniApp2 is successful will be added in miniApp successful invocations at time frame A after 10
If miniAppa2 has a delay in sending the data for more than five minutes (aka the miniApp ends at 10:06 but the JSON file is sent after 10:11) then it won’t be reported in real-time metrics, due to a five-minute watermark, but all data regardless delay will be captured in Convo Insights, in batch (historical) reporting.
There could be a request for miniApps Invocations for Time Interval A, Time Interval B, and also for Time Interval A+B (10:00-10:10), the last 10 minutes.
The sessions initiated will be added also at time frame B after 10:08, as the session was still active in that time frame and triggered a new miniApp.
Available Period for Real-Time Metrics
Real-time metrics will have a limited retention period of 48 hours. After this time range the metrics can be monitored, through Conversational Insights. For historical data, the user will be able to monitor their Applications through Convo Insights. In future versions of Metrics API, historical metrics will be also available, but instead of five-minute intervals, they will have one-hour intervals. The historical metrics will be reachable through a different endpoint.
OCP® Reporting for Real-Time Metrics
Metrics available through Metrics API are also available in Reporting UI within OCP® Insights. For more information, refer to the OCP® Reporting User Guide.