Overview
The Insights API is a service to retrieve call, message, and application data. The file you receive contains detailed information about your programmatic services. The lessons in this document can help you request and access the desired data, which can aid in:
-
General troubleshooting
-
Streamlining your processes
-
Analyzing customer behavior and experience
-
Creating new solutions to serve your customers
-
Fine-tuning existing SmartFlows to your customer experience
Request Limits
The maximum number of concurrent running queries per customer is two (2). The maximum amount of data each query can retrieve is approximately one (1) TB. Both of these limits generate an error. Check out the Max Concurrent Queries Reached example for more information.
Using the Insights API
-
GET https://api.intelepeer.com/_rest/v4/dwh/Q
Retrieves the list of fields available to design a custom query. Additional information about each field is available in the API Data Dictionary.
-
POST https://api.intelepeer.com/_rest/v4/dwh/Q
Validates and processes the query in the body of the request. A GUID is returned and subsequently used in later calls to check the status, headers, and location of the report. Your query is now processing.
-
GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}/status
Enables you to see the current status of your query. The API returns a response of Processing while your query is still processing. Once the API returns Completed, you are ready to download your report.
Note: The GUID is returned from the initial query request in Step 2.
-
GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}
Returns the location of the query output file on the SFTP server. For more information on how to access the SFTP server, check out File Storage Setup.
To retrieve only the HTTP headers associated with the file, change the request to HEAD as follows:
HEAD https://api.intelepeer.com /_rest/v4/dwh/Q/{guid}
Note: The GUID is returned from the initial query request in Step 2.
Examples
Example 1: Get Available Fields
Use this API to get a list of fields available for filtering and report shaping.
Note: Common Fields can be added to the data structure you use. For more information about each field, check out the API Data Dictionary.
Request
GET https://api.intelepeer.com/_rest/v4/dwh/Q
Authorization: Bearer 0sjey2…
Content-Type: application/json
Response (JSON)
Headers:
Status: 200
Content-Type: application/json
Body:
{
"ApplicationExitEvent": {
"fields": [
"StartTime",
"EndTime",
"Path",
"ExitReason"
]
},
"DtmfEvent": {
"fields": [
"DtmfInput",
"DtmfSource",
"ErrorReason"
]
}
}Example 2: Submit Query
Use the POST to validate and submit your query. The query accepts a JSON body with the following main attributes:
-
timestamp
Required. Restricts the date/time range of records to analyze during all phases of filtering and processing. If your scoped query is not providing the entire session, expand the range of your timestamp.
-
data
Required. Identifies which fields appear in the final report.
-
scope
Optional. Provides the ability to filter and collect associated records matching its own filters attribute. Similar to website analytics, a session correlates all actions for 1 user within 1 end-to-end execution of a flow.
-
If this attribute is used, both child attributes filters and scope must be provided
-
filters provide session filtering using MongoDB syntax:
-
$eq – equal to…
-
$gt – greater than…
-
$gte – greater than or equal to…
-
$lt – less than…
-
$lte – less than or equal to…
-
$ne – not equal to…
Note: Limited to the common field SessionId.
-
-
-
"filters"
Optional. Includes or excludes records during the final phase of filtering and processing; only matching data is returned.
-
If a scope filter is provided, filters may exclude individual records within a session.
-
Check out Design a Query for more information.
Request 1
Request all records that explicitly match criteria. This is the minimum acceptable query.
Explanation: This example limits your data to records occurring on or after ($gte) 2019-11-25 and on or before ($lte) 2019-11-26. The report only has one column: FlowId
POST https://api.intelepeer.com/_rest/v4/dwh/Q
Authorization: Bearer 0sjey2…
Content-Type: application/json
{
"timestamp": {
"$gte": "2019-11-25T00:00:00Z",
"$lte": "2019-11-26T00:00:00Z"
},
"data": {
"ApplicationExitEvent": {
"fields": ["FlowId"]
}
}
}Response (JSON)
Headers:
Status: 201
Content-Type: application/json
Content-Length: 43
Body:
{
"id": "ae9faa8e3cee29e5185578ad028e29f2"
}Request 2
Request any/all ApplicationExitEvent records associated to FlowId 5dcf48b453e0ab04386da7d1
POST /_rest/v4/dwh/Q
Authorization: Bearer 0sjey2n81hamxis=/
Content-Type: application/json
{
"timestamp": {
"$gte": "2019-11-25T00:00:00Z",
"$lte": "2019-11-26T00:00:00Z"
},
"data": {
"ApplicationExitEvent": {
"fields": ["EventName", "EventVersion", "EventSku", "TimeStamp",
"HostId", "CustomerId", "CustomerName", "Originator",
"OriginatorId", "FlowId", "FlowName", "ActionId", "ActionName",
"IsTriggerAction", "SessionId", "TransactionId",
"ApplicationRegion", "PassthroughVersion", "Passthrough",
"StartTime", "EndTime", "Path", "ExitReason"]
}
},
"filters": {
"ApplicationExitEvent": {
"FlowId": {"$eq": "5dcf48b453e0ab04386da7d1"}
}
}
}Response (JSON)
Headers:
Status: 201
Content-Type: application/json
Content-Length: 43
Body:
{
"id": "8dc9054b258c51f9ecf1f69322d69f9"
}Related Errors
The following errors can occur due to incorrect format or syntax in the Query API request body.
Incorrect Date Format
Dates should be in ISO-8601 format
Status: 400
{
"code": 400,
"message": {
"Date_Filters": {
"message": "Invalid date filters [2019-10-19 01:45:36.123Z]. They must be in ISO8601 format. Example: 'YYYY-MM-DDTHH:MM:SSZ'",
"code": "422-6"
}
}
}Incorrect Operators
Available operators: ($eq, $gt, $gte, $lt, $lte, $ne)
Status: 400
{
"code": 400,
"message": {
"Operators": "Invalid operators [gte, lte], try to use any of these ($gte, $lte, $gt, $lt, $ne, $eq)."
}
}Invalid Event Name
Event names and fields are case sensitive and must match the values provided by Get Available Fields.
Status: 400
{
"code": 400,
"message": "Application ExitEvent is not a valid schema name."
}Invalid Event Field Name
Event names and fields are case sensitive and must match the values provided by Get Available Fields
Status: 400
Status: 400
{
"code": 400,
"message": "Flow Id is not a valid field."
}Max Concurrent Queries Reached
Note: The maximum number of concurrent running queries per customer is two (2). The maximum amount of data each query can retrieve is approximately one (1) TB of data. Both of these limits generate this error message: max concurrent queries per user (2) reached.
In this case, there are too many queries/reports currently processing. Wait for others to finish. Check out the following error response example:
Status: 429
{
"code": 429,
"message": "max concurrent queries per user (2) reached"
}Example 3: Get Status Updates
Provides the ability to query/report status using the guid provided by Example 2. Continue using this API until the report has status Completed. All possible statuses are:
-
Canceled
Your query was canceled due to a timeout or other error
-
Completed
Report is completed.
-
Pending
Query is still in flight, keep checking until completed.
-
Failed
The query returned empty values.
Request
GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}/status
Authorization: Bearer 0sjey2…
Content-Type: application/json
Response (JSON)
Status: 200
{
"status": "Completed",
"guid": "a3a77e4c44818481c54bdfcf4d0f03bf"
}Related Errors
ID Not Found
The requested ID doesn’t exist in the database.
Status: 500
[
{
"message": "could not get QueryRequest object: QueryRequest matching query does not exist.",
"code": 500
}
]No Data Returned
The query returned empty values. Consider adding fields or correcting query to return a result.
Status: 200
{
"status": "Failed",
"guid": "cb141a8039e146ad954ca70e5c0d08d6",
"messages": [ "Query range to wide", "All data fields have empty values, advise adding core fields" ]
}Example 4: Get Results Download Link
Once the query status is completed, a request can be made to get the relative URL for the download. For more information on how to access your file, check out File Storage Setup.
Request
GET https://api.intelepeer.com/_rest/v4/dwh/Q/{guid}
Authorization: Bearer 0sjey2…
Content-Type: application/json
Response (JSON)
Status: 200
{
"status": "Process finished. Download: [u'reports/guid1/guid2_QueryExport_1579194142011__000000000000.csv.gz']",
"guid": "6ae69605c6e5ca352e664b0f96c8f84e"
}Related Errors
ID Not Found
The requested ID doesn’t exist in the database.
Status: 500
[
{
"message": "could not get QueryRequest object: QueryRequest matching query does not exist.",
"code": 500
}
]Process Has Not Finished
The results aren’t ready yet.
Status: 200
{
"status": "Process has not finish yet, please verify the status of your request",
"guid": "6ae69605c6e5ca352e664b0f96c8f84e"
}