Overview

The data API is a helper service to retrieve call, message, and application data. The file that you receive contains detailed information about your programmatic services. The lessons in this document will 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
Overview: Using Insights API
  1. GET /_rest/v4/dwh/Q retrieves a list of fields to query. Use these fields to design a query. A complete list of fields from the time of this writing can be found in the list of query fields
  2. POST /_rest/v4/dwh/Q validates and processes your query. A GUID is returned and should be stored for re-use in future calls; this GUID is required to check the status of your report

Within your query, the scope field limits results to sessions* matching its filters

*Similar to website analytics, a session correlates all actions for 1 user within 1 end-to-end execution of a flow

  1. The query runs
  1. GET /_rest/v4/dwh/Q/{guid}/status enables you to query status. Continue using this API until the report has status “Completed”
  2. HEAD /_rest/v4/dwh/Q/{guid} provides the HTTP headers associated to your report without sending the file.
  1. GET /_rest/v4/dwh/Q/{guid} downloads the file/report
 
Example 1: Get Available Fields

Use this API to get a list of fields available for filtering and report shaping.

GET /_rest/v4/dwh/Q

(no parameters)

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 4 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 will appear in the final report

 
scope

Optional. Provides the ability to filter and collect associated records. Currently limited to sessions. e.g. This attribute is used to find entire sessions that match its own filters attribute. Support for an App ID scope is under review.

– If this attribute is used, the both child attributes filters and scope must be provided

– filters provides 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…
 
filters

Optional. Includes or excludes records during the final phase of filtering and processing; only matching data will be returned.

  • If a scope filter is provided, filters may exclude individual records within a session

 

See Tutorial: Design a Query for more information.

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 will only have 1 column: FlowId

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": ["FlowId"]

   }

}

}

Headers:

Status: 201
Content-Type: application/json
Content-Length: 43

Body:

{
"id": "ae9faa8e3cee29e5185578ad028e29f2"
}

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"}

   }

 }

}

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.

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"
    }
  }
}

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)."
  }
}

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."
}

Event names and fields are case sensitive and must match the values provided by Get Available Fields

Status: 400
{
  "code": 400,
  "message": "Flow Id is not a valid field."
}

There are too many queries/reports currently processing. Please wait for others to finish.

Status: 429
{
  "code": 429,
  "message": "max concurrent queries per user (maximum_number_of_queries) 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:

  • Cancelled
  • Completed
  • Pending
  • Failed
GET /_rest/v4/dwh/Q/{guid}/status
Status: 200

{

 "status": "Failed",

 "guid": "cb141a8039e146ad954ca70e5c0d08d6",

 "messages": [ "Query range to wide", "All data.fields have empty values, advise adding core fields" ]

}
Related Errors
Status: 500

[

  {

    "message": "could not get QueryRequest object: QueryRequest matching query does not exist.",

    "code": 500

  }

]
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.

GET /_rest/v4/dwh/Q/{guid}
Status: 200

{

  "status": "Process finished. Download: [u'reports/guid1/guid2_QueryExport_1579194142011__000000000000.csv.gz']",

  "guid": "6ae69605c6e5ca352e664b0f96c8f84e"

}
Related Errors

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

  }

]

The results aren’t ready yet.

Status: 200

{

  "status": "Process has not finish yet, please verify the status of your request",

  "guid": "6ae69605c6e5ca352e664b0f96c8f84e"

}