API Reference

The Real User Monitoring API allows customers to query for session information from Raygun. It has two endpoints; one for aggregate session information, and one for individual session information.

The Real User Monitoring API is only available to customers on enterprise plans


The API provides two main query endpoints and an authentication endpoint. The first endpoint provides a search for user sessions and will return a paged list with cut down session details. The second endpoint provides a call to get the full session details for a single session using the session Id returned in the search endpoint.

  • GET Authenticate
  • GET Sessions
  • GET Session

note:

  • All datetimes are in ISO 8061 UTC format
  • All calls have a 30 second timeout.
  • By default, a rate limit of 50 calls per day will apply per application.


Authentication to the Raygun API is handled through a time limited token passed in the X-SessionKey header of all requests. To get a session key you are required to call the authenticate endpoint with your Raygun application API key and basic authentication username and password. The API key for your application is provided under the Application settings in Raygun. The basic authentication username and password are generated by creating a consumer application under your Raygun plan and using the client ID as the username and client secret as the password.

To get your basic authentication username and password:

  1. Navigate to your plan settings in top right dropdown, clicking on your plan name.

  2. Click on the Consumers tab and then click Register Application.

  3. Enter your applications details (note authorization callback URL is not used and can be set to any valid URL) and click Register.

  4. Copy the Client ID and Client Secret. These are the username and password in the authenticate call basic authorization header.


GET https://api.raygun.com/api/v1/pulse/authenticate

Authenticate with the Real User Monitoring API and retrieve a time limited session key for subsequent requests.

Name Located in Description Required Data type
X-ApiKey header Application API key Yes string

Example request

curl -X POST -H "X-ApiKey: [YOUR_APPLICATION_API_KEY]" -H "Authorization: Basic [Base64 encoded ClientID:ClientSecret]" "https://api.raygun.com/api/v1/pulse/authenticate"
{
  // A session key to be supplied in the X-SessionKey header for subsequent requests. Valid for 15 minutes.
  "sessionKey": "string"
}

202 Accepted.

401 Unauthorized. API key or Authorization headers not supplied, or invalid.

500 Server error. Contact Raygun for further information.


GET https://api.raygun.com/api/v1/pulse/sessions

Search for sessions using a variety of parameters to return a paged list of sessions.

Name Located in Description Required Data type
X-SessionKey header A valid session key Yes string
dateFrom query Start of date range Yes date-time
dateTo query End of date range Yes date-time
userIdentifier query A provided user identifier to limit results to a single user. No string
country query An array of country codes to limit results. No Array[string]
userType query Limits the type of user based on the selected option. No string
skip query Skip the list of returned results by this amount. Default is zero. No integer
limit query Number of items to retrieve. Default is 50, maximum is 500. No integer

Example request

curl -X GET -H "x-sessionkey: [YOUR_SESSION_KEY]" "https://api.raygun.com/api/v1/pulse/sessions?dateFrom=2016-12-01&dateTo=2016-12-21&country=US,NZ&skip=0&limit=10"
{
  // The total number of sessions
  "totalSessions": 0,
  // List of sessions for the current page of results
  "sessions": [
    {
      // Unique Id for the session
      "id": 0,
      // The date and time the session started
      "sessionStart": "2017-01-25T01:18:25.854Z",
      // The date and time the session was last updated
      "sessionUpdated": "2017-01-25T01:18:25.854Z",
      // The date and time the session ended (can be null)
      "sessionEnd": "2017-01-25T01:18:25.854Z",
      "user": {
        // Unique Id for the user
        "id": 0,
        // Flag indicating if this is an anonymous user
        "isAnonymous": true,
        // Provided user identifier
        "identifier": "string",
        // The first name of the user
        "firstName": "string",
        // The full name of the user
        "fullName": "string",
        // The email address of the user
        "emailAddress": "string",
        // The date and time the user was first seen (can be null)
        "firstSeen": "2017-01-25T01:18:25.854Z",
        // The date and time the user was last seen (can be null)
        "lastSeen": "2017-01-25T01:18:25.854Z",
        "links": {
          // Web app URL to the user
          "web": "string"
        }
      },
      "browser": {
        // The display name of the browser
        "name": "string",
        // The full version number of the browser
        "version": "string"
      },
      "platform": {
        // The display name of the platform
        "name": "string"
      },
      "os": {
        // The display name of the operating system
        "name": "string",
        // The full version number of the operating system
        "version": "string"
      },
      "location": {
        // The 2 digit country code
        "country": "string",
        // The public IP address used to determine the location
        "ipAddress": "string"
      },
      // Total length of the session in milliseconds
      "sessionLength": 0,
      // Current status of the session (active or ended)
      "status": "string",
      // Total count of page views for this session
      "pageViewCount": 0,
      "links": {
        // API URL to the session
        "self": "string",
        // Web app URL to the session
        "web": "string"
      }
    }
  ],
  "links": {
    // API URL to the current page of results
    "self": "string",
    // API URL to the next page of results (can be null)
    "next": "string",
    // API URL to the previous page of results (can be null)
    "previous": "string"
  }
}

200 OK. A paged list of sessions.

400 Bad request. Check all required fields have been specified and values are in the expected format.

401 Unauthorized. API key or Authorization headers not supplied, or invalid.

429 Rate limited. Too many requests within the specified period of time.

500 Server error. Contact Raygun for further information.


GET https://api.raygun.com/api/v1/pulse/session

Retrieve detailed session data for a single session.

Name Located in Description Required Data type
X-SessionKey header A valid session key Yes string
id query Session Id Yes int64

Example request

curl -X GET -H "x-sessionkey: [YOUR_SESSION_KEY]" "https://api.raygun.com/api/v1/pulse/sessions?id=1234567890"
{
  "session": {
    // Unique Id for the session
    "id": 0,
    // The date and time the session started
    "sessionStart": "2017-01-25T01:18:25.878Z",
    // The date and time the session was last updated
    "sessionUpdated": "2017-01-25T01:18:25.878Z",
    // The date and time the session ended (can be null)
    "sessionEnd": "2017-01-25T01:18:25.878Z",
    "user": {
      // Unique Id for the user
      "id": 0,
      // Flag indicating if this is an anonymous user
      "isAnonymous": true,
      // Provided user identifier
      "identifier": "string",
      // The first name of the user
      "firstName": "string",
      // The full name of the user
      "fullName": "string",
      // The email address of the user
      "emailAddress": "string",
      // The date and time the user was first seen (can be null)
      "firstSeen": "2017-01-25T01:18:25.878Z",
      // The date and time the user was last seen (can be null)
      "lastSeen": "2017-01-25T01:18:25.878Z",
      "links": {
        // Web app URL to the user
        "web": "string"
      }
    },
    // The overall satisfaction rating for the session. = ['Excellent', 'Good', 'Average', 'Poor']
    "satisfactionRating": "Excellent",
    "browser": {
      // The display name of the browser
      "name": "string",
      // The full version number of the browser
      "version": "string"
    },
    "platform": {
      // The display name of the platform
      "name": "string"
    },
    "os": {
      // The display name of the operating system
      "name": "string",
      // The full version number of the operating system
      "version": "string"
    },
    "location": {
      // The 2 digit country code
      "country": "string",
      // The public IP address used to determine the location
      "ipAddress": "string",
      "ipLookup": {
        // The Country name
        "country": "string",
        // The State or Region name
        "state": "string",
        // The City name
        "city": "string"
      }
    },
    // Total length of the session in milliseconds
    "sessionLength": 0,
    // Current status of the session (active or ended)
    "status": "string",
    // List of errors that occurred in this session
    "errors": [
      {
        // Unique identifier for the error group
        "groupId": 0,
        // Unique identifier for the error instance
        "instanceId": 0,
        // Title of the error group
        "title": "string",
        "links": {
          // Web app URL to the error instance
          "web": "string"
        }
      }
    ],
    // List of page views for this session
    "pageViews": [
      {
        // The URL of the page
        "page": "string",
        // Total load time of the page view in milliseconds
        "loadingTime": 0,
        // Total time spent viewing the page view in milliseconds
        "viewingTime": 0,
        // The date and time the page was viewed
        "viewedOn": "2017-01-25T01:18:25.879Z"
      }
    ],
    "links": {
      // API URL to the session
      "self": "string",
      // Web app URL to the URL
      "web": "string"
    }
  }
}

200 OK. A detailed session object.

400 Bad request. Check all required fields have been specified and values are in the expected format.

401 Unauthorized. API key or Authorization headers not supplied, or invalid.

404 Not found. The specified resource was not found.

429 Rate limited. Too many requests within the specified period of time.

500 Server error. Contact Raygun for further information.