Traces

Trace records are generated when an Application interacts with the CPaaS platform. Everytime the Application uses the Calls or Messages API to interact with users on the different communication channels, a new record will be generated.

Trace records will also be generated every time the CPaaS platform needs to contact the CPaaS Application (to download RCML documents for incoming traffic, to send status callback reports, etc.).

The Traces API endpoint supports JSON output only.

Traces need to be activated on your subscriber profile.

The retention policy for this resource is 2 days only, because of the amount of data generated.

Traces Resource URI

/2012-04-24/Accounts/{AccountSid}/Traces/{TraceSid}

Resource Properties

Property Description

Property	Description
api_version	The API version in use during the recording.
sid	A string that uniquely identifies this record.
date_created	The date on which this record was created. This is corresponding to the time when response arrived to the original client.
account_sid	The unique id of the Account that created this record.
org_sid	The unique id of the Organization which belongs to the Account.
session_sid	The unique id of the call/message related to this interaction.
status	The status of the HTTP transaction. `completed` in case the response status code is in the 2XX range. `failed` in case response status code is not 2XX.
uri	The URI for this record, relative to `\https://$DOMAIN/api`.
direction	`webhook` in case CPaaS platform sends the request. `api` in case the CPaaS Application sends the request.
latency_ms	Number of millis between request and response.
request.path	URI path including query parameters.
request.method	`GET\|POST`
request.headers	JSON Map containing all headers included in the HTTP request.
request.body	The request body or empty if no content. If body is text, it should be encoded as text, otherwise trim content to 100 KB.
response.status.code	The HTTP response status code.
response.status.phrase"	The HTTP response status phrase.
response.headers	JSON map containing all headers included in the HTTP response.
response.body	An HTTP response body, or empty if no content. If body is text, it should be encoded as text, otherwise the content will be trimmed to 100 KB.

api_version

The API version in use during the recording.

sid

A string that uniquely identifies this record.

date_created

The date on which this record was created. This is corresponding to the time when response arrived to the original client.

account_sid

The unique id of the Account that created this record.

org_sid

The unique id of the Organization which belongs to the Account.

session_sid

The unique id of the call/message related to this interaction.

status

The status of the HTTP transaction. completed in case the response status code is in the 2XX range. failed in case response status code is not 2XX.

uri

The URI for this record, relative to \https://$DOMAIN/api.

direction

webhook in case CPaaS platform sends the request. api in case the CPaaS Application sends the request.

latency_ms

Number of millis between request and response.

request.path

URI path including query parameters.

request.method

GET|POST

request.headers

JSON Map containing all headers included in the HTTP request.

request.body

The request body or empty if no content. If body is text, it should be encoded as text, otherwise trim content to 100 KB.

response.status.code

The HTTP response status code.

response.status.phrase"

The HTTP response status phrase.

response.headers

JSON map containing all headers included in the HTTP response.

response.body

An HTTP response body, or empty if no content. If body is text, it should be encoded as text, otherwise the content will be trimmed to 100 KB.

Supported Operations

HTTP GET Returns the representation of a Trace resource, including the properties above.

Listing a Singe Trace Record

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACea59167c974743ecb8dbe4cc8bb85712/Traces/TRc377eb0e657e415383de087ab38797db  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACea59167c974743ecb8dbe4cc8bb85712/Traces/TRc377eb0e657e415383de087ab38797db',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACea59167c974743ecb8dbe4cc8bb85712/Traces/TRc377eb0e657e415383de087ab38797db',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACea59167c974743ecb8dbe4cc8bb85712/Traces/TRc377eb0e657e415383de087ab38797db");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The response will be similar to the one below.

{
  "sid" : "TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account_sid" : "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "account_friendly_name" : "account name",
  "org_sid" : "ORfe81fe8a3d5f4d5391e901db0bf5755d",
  "org_name" :"customer.company.com",
  "date_created_ms" : "Wed, 30 Jun 2021 16:41:09.456 +0000",
  "session_sid" : "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
  "uri": "/Accounts/AC1234/Traces/TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "status" : "completed",
  "direction" : "webhook",
  "latency_ms": 564,
  "request": {
    "path" : "/cpaasAppPath?AccountSid=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "method" : "GET",
    "headers" : {
      "accept" : "application/xml"
    },
    "body" : ""
  }
  ,
  "response" : {
    "status" : {
      "code" : "200",
      "phrase" : "OK",
      "headers" : {
        "content-length" : 43,
        "content-type" : "application/xml"
      },
      "body" : "<Response><say> hello world</say><Response>"
    }
  }

}

Traces List Resource

Traces List Resource URI

/2012-04-24/Accounts/{AccountSid}/Traces

Supported Operations

HTTP GET

Returns the list representation of all the Trace records resources for a given account, including the properties above.

Getting a List of Trace Records

Here is how you can list your records:

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The response will be similar to the one below.

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces","first_page_uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?Page=0&PageSize=50","traces":
    [
        {
          "sid" : "TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "account_sid" : "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "account_friendly_name" : "account name",
          "org_sid" : "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "org_name" :"customer.company.com",
          "date_created_ms" : "Wed, 30 Jun 2021 16:41:09.456 +0000",
          "session_sid" : "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "uri": "/Accounts/AC1234/Traces/TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "status" : "completed",
          "direction" : "webhook",
        "latency_ms": 564,
          "request": {
            "path" : "/cpaasAppPath?AccountSid=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "method" : "GET",
            "headers" : {
              "accept" : "application/xml"
            },
            "body" : ""
          }
          ,
          "response" : {
            "status" : {
              "code" : "200",
              "phrase" : "OK",
              "headers" : {
                "content-length" : 43,
                "content-type" : "application/xml"
              },
              "body" : "<Response><say> hello world</say><Response>"
            }
          }

        },
        ...

    ]
}

List Filter

HTTP GET

The following GET query string parameters allow you to limit the list returned.

All request parameters are case-sensitive.

Request Parameters

Parameter Description

Parameter	Description
Status	Only show records that match with this status.
DateCreated	Only show records that started on this date/time or later, given as an ISO-8601 date/time string, like `YYYY-MM-DDTHH:MM:SS` (for example 2018-10-05T22:45:32). If you want to omit the time, `YYYY-MM-DD` (for example 2018-10-05). If only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.
SessionSid	Only show records spawned by the call/message with this Sid.
Latency	Only show records which Latency is equal or over the given value in milliseconds
Direction	Only show records that match specific direction - "webhook"/"API"
ResponseCode	Only show records that match specific Response Code. Can be used for prefix match, for example ResponseCode=2 will match all 2xx response codes
ResponseBody	Only show records that Response Body match provided filter string
RequestPath	Only show records that Request Path match provided filter string. Can be used for prefix match, for example RequestPath='https://s3.amazonaws.com' will match all Traces with Request Path to 'https://s3.amazonaws.com'
AccountSid	Only show records that match Account Sid
OrgSid	Only show records that match Organization Sid

Status

Only show records that match with this status.

DateCreated

Only show records that started on this date/time or later, given as an ISO-8601 date/time string, like YYYY-MM-DDTHH:MM:SS (for example 2018-10-05T22:45:32). If you want to omit the time, YYYY-MM-DD (for example 2018-10-05). If only a date is provided the time is assumed to be at midnight of the given date. Note that the given date/time is inclusive and is assumed to be in the UTC timezone. A 400 response will be returned if the syntax is invalid.

SessionSid

Only show records spawned by the call/message with this Sid.

Latency

Only show records which Latency is equal or over the given value in milliseconds

Direction

Only show records that match specific direction - "webhook"/"API"

ResponseCode

Only show records that match specific Response Code. Can be used for prefix match, for example ResponseCode=2 will match all 2xx response codes

ResponseBody

Only show records that Response Body match provided filter string

RequestPath

Only show records that Request Path match provided filter string. Can be used for prefix match, for example RequestPath='https://s3.amazonaws.com' will match all Traces with Request Path to 'https://s3.amazonaws.com'

AccountSid

Only show records that match Account Sid

OrgSid

Only show records that match Organization Sid

Filtering by SessionSid Parameter

The example below will return records that have been initiated from this CallSid.

curl -X GET https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?SessionSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49  \
   -u 'YourAccountSid:YourAuthToken'

const request = require('request');

// Provide your Account Sid and Auth Token from your Console Account page
const ACCOUNT_SID = 'my_ACCOUNT_SID';
const AUTH_TOKEN = 'my_AUTH_TOKEN';

request({
      method: 'GET',
      url: 'https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?SessionSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      auth: { 'user': ACCOUNT_SID, 'pass': AUTH_TOKEN }
   },
   function (error, response, body) {
      // Add your business logic below; status can be found at 'response.statusCode' and response body at 'body'
      ...
   }
);

from http.client import HTTPSConnection
from base64 import b64encode

# Provide your Account Sid and Auth Token from your Console Account page
ACCOUNT_SID = 'my_ACCOUNT_SID'
AUTH_TOKEN = 'my_AUTH_TOKEN'

userAndPass = b64encode(bytes(ACCOUNT_SID + ':' + AUTH_TOKEN, 'utf-8')).decode("ascii")
headers = { 'Authorization' : 'Basic %s' %  userAndPass }

conn = HTTPSConnection('mycompany.restcomm.com')
conn.request("GET", '/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?SessionSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49',
      headers=headers)
res = conn.getresponse()

# Add your business logic below; status can be found at 'res.status', reason at 'res.reason' and response body can be retrieved with res.read()
...

import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import java.io.*;
import java.util.Base64;

public class JavaSampleClass {
   // Provide your Account Sid and Auth Token from your Console Account page
   public static final String ACCOUNT_SID = "my_ACCOUNT_SID";
   public static final String AUTH_TOKEN = "my_AUTH_TOKEN";


   public static void main(String[] args) throws Exception {
      String userAndPass = ACCOUNT_SID + ':' + AUTH_TOKEN;
      String encoded = Base64.getEncoder().encodeToString(userAndPass.getBytes());

      URL url = new URL("https://mycompany.restcomm.com/restcomm/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?SessionSid=IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49");
      HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
      conn.setRequestProperty("Authorization", "Basic " + encoded);
      conn.setRequestMethod("GET");

      // Add your business logic below; response code can be obtained from 'conn.getResponseCode()' and input stream from 'conn.getInputStream()'
      ...
  }
}

The result will be similar to the one below

{"page":0,"num_pages":0,"page_size":50,"total":34,"start":"0","end":"34","uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces","first_page_uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?Page=0&PageSize=50","previous_page_uri":"null","next_page_uri":"null","last_page_uri":"/api/2012-04-24/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Traces?Page=0&PageSize=50","traces":
    [
        {
          "sid" : "TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "account_sid" : "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "account_friendly_name" : "account name",
          "org_sid" : "ORfe81fe8a3d5f4d5391e901db0bf5755d",
          "org_name" :"customer.company.com",
          "date_created_ms" : "Wed, 30 Jun 2021 16:41:09.456 +0000",
          "session_sid" : "IDbb44ef8c2ebf4d4599d0378a2a8a2ea8-CAd9e08ede8b604e739ba7d0bd477fdf49",
          "uri": "/Accounts/AC1234/Traces/TRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
          "status" : "completed",
          "direction" : "webhook",
          "latency_ms": 564,
          "request": {
            "path" : "/cpaasAppPath?AccountSid=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "method" : "GET",
            "headers" : {
              "accept" : "application/xml"
            },
            "body" : ""
          }
          ,
          "response" : {
            "status" : {
              "code" : "200",
              "phrase" : "OK",
              "headers" : {
                "content-length" : 43,
                "content-type" : "application/xml"
              },
              "body" : "<Response><say> hello world</say><Response>"
            }
          }

        },
        ...
    ]
}

Paging Information

The request supports standard paging information. For more details, please visit the Paging Information documentation.

Trace Records for cached resources

When media resources for Play, Dial, Conference webhooks are already cached (see Cache Strategy) Trace Records will not be generated since the access to the CPaaS application will be skipped.

Let’s see an example of when Call Detail Records will be generated.

Restcomm CPaaS platform executes a Play verb, accesses external service and caches the resulted resource file.
- Restcomm CPaaS platform generates a Trace Record
Restcomm executes a Play verb with the same content as before but now since the resulted resource file is already cached, access to the external service will be skipped.
- Restcomm will not generate a Trace Record