API Reference

Welcome to the Inspectlet API! You can use our API to retrieve and search your session recordings with a simple JSON-based REST interface.

We have language bindings and examples available in Shell, Javascript, and PHP! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

The sample code below uses a dummy username and API token, please replace them with your own credentials.

// prep the header we need to send for HTTP Basic Auth
var username = "bob@example.com";
var apitoken = "af9f27cd9c02b54a9bead349662dddf4a7ea1430";
var headers = {"Authorization": "Basic " + btoa(username + ":" + apitoken)};

Inspectlet uses HTTP Basic Authentication to allow access to the API and your account data. Every request to the API should be signed with your account’s email address and API token. You can find your API token by logging into your Inspectlet dashboard and looking under “API Credentials” on the “your account” page.

Username: bob@example.com

Password: APITOKEN

Please replace APITOKEN with your personal API token.

Errors

If there are no errors with your API request, the Inspectlet API will return a 200 HTTP response containing a JSON object with a response property.

If there’s an error with your request, Inspectlet will return a JSON object with an error property and one of the following HTTP error codes:

Error Code	Meaning
400	Bad Request – Your request could not be completed.
401	Unauthorized – Your API token is invalid or you don’t have access to that resource.
429	Too Many Requests – Your API token is being rate-limited due to too many requests in a short span of time.

Listing Your Sites

// list all the sites in your account
$.ajax({
  url: 'https://api.inspectlet.com/v1/websites',
  headers: {"Authorization": "Basic " + btoa('bob@example.com:af9f27cd9c02b54a9bead349662dddf4a7ea1430')},
  success: function (apiResponse){
    console.log(apiResponse);
  }
});

The above command returns JSON structured like this:

{
  "response": [
    {
      "wid": 12345678,
      "site_name": "My App",
      "date_added": 1337677548
    }
  ]
}

List all the sites in your account.

HTTP Request

GET https://api.inspectlet.com/v1/websites

Response Parameters

Returns an array containing an object for each site in your account.

Parameter	Description
wid	The website’s ID, used to make calls to other API endpoints about this site.
site_name	The site’s name.
date_added	The date the website was created.

Listing and Searching Sessions

// search for session recordings of visitors from United States
$.ajax({
  type: "POST",
  url: 'https://api.inspectlet.com/v1/websites/12345678/sessions',
  headers: {"Authorization": "Basic " + btoa('bob@example.com:af9f27cd9c02b54a9bead349662dddf4a7ea1430')},
  data: {
    search: JSON.stringify({
      country: "US"
    })
  },
  success: function (apiResponse){
    console.log(apiResponse);
  }
});

// search for session recordings from the last week tagged with converted=true
$.ajax({
  type: "POST",
  url: 'https://api.inspectlet.com/v1/websites/12345678/sessions',
  headers: {"Authorization": "Basic " + btoa('bob@example.com:af9f27cd9c02b54a9bead349662dddf4a7ea1430')},
  data: {
    search: JSON.stringify({
      daterange   : "week",
      tags        : {
        tagslist  : [
          {
            tag   : "converted",
            value : true
          }
        ]
      }
    })
  },
  success: function (apiResponse){
    console.log(apiResponse);
  }
});

The above commands return JSON structured like this:

{
  "response": [
    {
      "sid": 2606721012,
      "wid": 12345678,
      "date_start_session": 1446772479,
      "date_end_session": 1446772768,
      "session_duration": 286893,
      "num_pages": 1,
      "uid": 2099309727,
      "ip": "53.68.13.141",
      "browser": "chrome",
      "referrer": {
        "source": "d"
      },
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
      "new_visitor": true,
      "starred": false,
      "country": "US",
      "landing_page": "http://www.example.com\/?utm_campaign=media",
      "exit_page": "http://www.example.com\/product-1123",
      "device_type": "desktop",
      "display_name": "Johnny Appleseed",
      "sessionlink": "http://www.inspectlet.com/dashboard/watchsession/12345678/2606721012?pn=1&accessResourceKey=2e1a5838e3c823cf1b754e5dd9e4f2a775eb9bfd",
      "tags": [
        {
          "tag": "converted-purchase",
          "value": "1",
          "timestamp": 1446772657
        },
        {
          "tag": "email",
          "value": "johnny.appleseed@gmail.com",
          "timestamp": 1446772552
        }
      ],
      "pages": [
        {
          "rid": 2017992525,
          "opened_at": 1446772479,
          "pagetitle": "Title of first page in session.",
          "url": "http://www.example.com\/?utm_campaign=media"
        }
      ]
    }
  ]
}

Search for and retrieve session recordings for your website. If the search variable is left undefined, Inspectlet will return the most recent sessions for your site.

HTTP Request

POST https://api.inspectlet.com/v1/websites/<wid>/sessions

Request Parameters

Parameter	Default	Description
wid		Your website ID.
search		(Optional) If this variable is set, the resulting sessions will match this search query. See Searching for Sessions for more details.
limit	10	(Optional) The maximum number of sessions to return in one response. A maximum of 100 sessions can be returned at once.
page	1	(Optional) The page number to scroll to for result pagination.

Searching for Sessions

When using the search parameter to find sessions matching specific conditions, the following properties can be specified in an object to build a search query:

The search object accepts multiple search parameters allowing you to create complex searches.

Parameter	Description
displayname	Visitor’s display name as it was sent in when identifying your users.
country	Visitor’s ISO-639 country code (e.g. “US” for United States)
newold	An object with the following properties: `newold.new` boolean - whether to include new visitors `newold.old` boolean - whether to include returning visitors
tags	An object with the following properties: `tags.tagslist` array of tag objects - each object represents a tag and has two string properties: tag (required),value (optional). `tags.operator` (Optional) and/or - The operator to use when multiple tags are specified in tags.tagslist. Choose “and” to require all tags in tags.tagslist to be matched. Choose “or” to return sessions that include any tags specified in tags.tagslist. Default operator is and.
ipaddress	string IP address of visitor (e.g. “67.128.22.4”)
showstarredonly	boolean Whether to only include starred session recordings.
browser	string A browser name (chrome/firefox/safari/mobile safari/chrome mobile (ios)/ie/android/opera/other).
devices	string A device category (all/phone/desktop).
daterange	string The time span that the results should search in. Possible values are: “30days”,“week”,“custom” (see daterangecustom)
daterangecustom	An object with the following properties: `daterangecustom.start` string - the Unix timestamp results should start from `daterangecustom.end` string - the upper bound Unix timestamp for search results
seslength_start	integer The minimum session duration in pages. `seslength_end` can also be specified to control the max number of pages in the session.
sestime_start	integer The minimum session duration in seconds. `sestime_end` can also be specified to control the max session duration.
startpage	Search for sessions starting from a specific landing page. See Searching by URLs.
visitedpage	Search for sessions starting containing a specific page. See Searching by URLs.
exitpage	Search for sessions starting with a specific exit page. See Searching by URLs.
trafficsource	string The traffic source

Searching by URLs

// Search for all sessions starting from www.example.com/page
{
  search: JSON.stringify({
    "startpage" : {
      "operator"  : "is",
      "url"       : "www.example.com/page"
    }
  })
}

// Search for all sessions containing a page whose URL starts with www.example.com/profile/*
// (i.e. www.example.com/profile/john, www.example.com/profile/bob)

{
  search: JSON.stringify({
    "visitedpage" : {
      "operator"  : "beginswith",
      "url"       : "www.example.com/profile/"
    }
  })
}

When filtering for sessions with a specific startpage, visitedpage, or exitpage, the URL search is represented as an object with the following properties:

url The URL string to search for.

operator Type of match - Possible options for URL match: is, beginswith, contains, patternmatch, notis, notbeginswith, notcontains. Defaults to is.

operator	Description
is	exact URL match (www.example.com/test-page.html)
beginswith	match URLs that begin with the URL fragment (www.example.com/test-page.html will match www.example.com/test-page.html?utm_campaign=banner)
contains	match URLs that contain the URL fragment (/dash/ will match www.example.com/dash/profile)
patternmatch	match URLs that match a wildcard pattern (dash will match www.example.com/dash/profile)
notis	does not exactly match the specified URL
notbeginswith	does not begin with the specified URL fragment
notcontains	does not contain the specified URL

Response Parameters

Returns a JSON object containing an array of matching sessions. Each session is an individual session object.

Retrieving an Individual Session

// fetch information about an individual session
$.ajax({
  url: 'https://api.inspectlet.com/v1/websites/12345678/sessions/2606721012',
  headers: {"Authorization": "Basic " + btoa('bob@example.com:af9f27cd9c02b54a9bead349662dddf4a7ea1430')},
  success: function (apiResponse){
    console.log(apiResponse);
  }
});

The above command returns JSON structured like this:

{
  "response": [
    {
      "sid": 2606721012,
      "wid": 12345678,
      "date_start_session": 1446772479,
      "date_end_session": 1446772768,
      "session_duration": 286893,
      "num_pages": 1,
      "uid": 2099309727,
      "ip": "53.68.13.141",
      "browser": "chrome",
      "referrer": {
        "source": "d"
      },
      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
      "new_visitor": true,
      "starred": false,
      "country": "US",
      "landing_page": "http://www.example.com\/?utm_campaign=media",
      "exit_page": "http://www.example.com\/product-1123",
      "device_type": "desktop",
      "display_name": "Johnny Appleseed",
      "sessionlink": "http://www.inspectlet.com/dashboard/watchsession/12345678/2606721012?pn=1&accessResourceKey=2e1a5838e3c823cf1b754e5dd9e4f2a775eb9bfd",
      "tags": [
        {
          "tag": "converted-purchase",
          "value": "1",
          "timestamp": 1446772657
        },
        {
          "tag": "email",
          "value": "johnny.appleseed@gmail.com",
          "timestamp": 1446772552
        }
      ],
      "pages": [
        {
          "rid": 2017992525,
          "opened_at": 1446772479,
          "pagetitle": "Title of first page in session.",
          "url": "http://www.example.com\/?utm_campaign=media"
        }
      ]
    }
  ]
}

Retrieve information about an individual session recording.

HTTP Request

GET https://api.inspectlet.com/v1/websites/<wid>/sessions/<sid>

Request Parameters

Parameter	Description
wid	Your website ID.
sid	The session ID.

Response Parameters

Returns a JSON object containing information about the session:

Parameter	Description
sid	The session ID.
wid	The website ID.
date_start_session	The session’s start time in UTC.
date_end_session	The session’s last recorded activity in UTC.
session_duration	The total session duration in seconds.
num_pages	The total number of pages in this session.
uid	The user’s internal identifier used by Inspectlet.
ip	The user’s IP address.
browser	The user’s browser’s major family name.
referrer	The referring traffic source of this session.
page_width	The browser page width.
page_height	The browser page height.
useragent	The user’s browser’s complete user agent string.
new_visitor	A boolean indicating whether or not this session is the first session from this user on this website.
starred	A boolean indicating whether this session is starred.
country	The visitor’s ISO-639 country code (e.g. “US” for United States).
landing_page	The URL of the first page in the session.
exit_page	The URL of the last page in the session.
device_type	The type of device used during this visit (desktop/phone).
display_name	Visitor’s display name as it was sent in when identifying your users.
sessionlink	A guest-accessible, sharable URL to watch this session recording.
tags	An array of tags associated with this session.
pages	The list of pages the user visited in this session.