NAV

Introduction

The Query API for mPulse is a unified REST API that allows mPulse customers to fetch aggregate data and receive a JSON response with mPulse data. Data sets, navigation timing, custom timers, and metrics are supported. Data for a given date is aggregated per minute for the given 24-hour period. Data returned will always be limited to one calendar day in the timezone. If the date is ‘today’ it is still aggregated per minute, only from midnight to the current time (e.g. the time of the query).

For some charts, such as the Last 30 Days chart on the “Load Time vs. Page Views widget, it is necessary to call the Summary API 30 times (or the correct number of days for the given month) to get all the summary aggregate data for the time period.

Drilldowns are supported but not all combinations (mostly dimensions) are supported. For example, drilldowns by page groups + browsers + A/B tests are supported. When a drilldown by a combination is not supported, its response will contain no data.

This API uses HTTP in the following ways:

mPulse Query API, Version 2

Version 2 is the current version of the mPulse Query API and uses the API KEY as an identifier in the API.

Authentication

For information about Tokens API, see Tokens_API.

To use the REST APIs, callers will issue a request using the mPulse URL shown below to get a security token. Note that the mPulse API URL is case sensitive. For example, to get a token from a mPulse instance via its RepositoryService:

Specify a username and account to get the security token used in later queries.

curl -X PUT -H "Content-type: application/json" --data-binary '{"userName":"<username>", "password":"xxxxx"}' "https://mpulse.soasta.com/concerto/services/rest/RepositoryService/v1/Tokens"

Note: Users who belong to multiple tenants and wish to obtain a security token for a tenant that is not their default, can add the "tenant” key to the JSON body; for example, “tenant”: “My Tenant”.

Will get the response: {"token":"da7be4d72030656559f3e41a98924a6b2a544730"}

Wrappers

repository.js

REST API URLs

Once a security token is acquired, it is used in all subsequent queries within the validity period. The URLs for accessing the REST API use the token, the mPulse instance, the domain, the query type(s), and any optional parameters that go with the query type, and take the following format:

/concerto/api/v2/<api-key>/<query-type>?<optional parameters>

If curl is used, the command line looks like this:

curl -H "Authentication: <security token>" "https://mpulse.soasta.com/mpulse/api/v2/<api-key>/<query type>?<optional parameters>"

Specifying the JSON Output Format

The format=json argument is used to control excess slashes, which can occur in some cases.

curl -H "Authentication: 3c8cc11f-f1d-966-4015-a93a-c00676f40c68" "https://mpulse.soasta.com/concerto/mpulse/api/v2/ANYDU-8VSVE-ZBBD3-998BR-HKLUC/timers-metrics?date=2014-12-16&format=json"

Parameters

This Query API has the following query type and query type parameters for collection of aggregate data.

The following query parameters can be added to the query string of a request to filter and control the response.

Optional Query Type Parameters (All query types)

Date Parameters

Use these parameters to modify the time window of the api call.

date: The date parameter is specified in “YYYY-MM-DD” format (ISO 8601). The current day is assumed if it’s absent.

date-comparator: Specify the date-comparator to use by name and then provide its required parameters, if any. If Between or Last are used, then the date parameter is specified in “YYYY-MM-DD” format (ISO 8601). The current day is assumed if it’s absent.

For the date-comparator query type, the following time windows are supported:

timezone: The timezone parameter is specified as a string value, which must be the same as those on the drop-down list on the mPulse dashboard (default: UTC). Timezone names must be parse-able by Java (i.e. US/Eastern, Europe/London, Asia/Shanghai, etc.).

Timer Parameters

Use these parameters to modify the timer data returned by api calls.

timer: The timer parameter can be one of the following:

Note: Because the index of the CustomTimer parameter (e.g. timer=CustomTimer[0-9] was difficult to use, this parameter has been deprecated as of mPulse 54.1.5. Use the preferred custom-timer parameter (next row) instead.

custom-timer: The custom-timer parameter is specified as the UI name of the given custom timer (e.g. the explicit name of the custom timer as found in the Configure Apps, Custom Timers tab).For example, if a custom timer for a domain or app is named MapImageLoad, then use: custom-timer=MapImageLoad

percentile: The percentile can be any positive numeric value between 1 and 99.

Dimension Parameters

Note that you need to use a “+” for spaces.

Use these parameters to filter the returned by api calls. Use them as you’d use the mPulse dashboard filters.

ab-test: ab-test is the equivalent of the AB Test filter in the mPulse UI. An example usage would be ab-test=fastly. The legacy parameter test has the same functionality.

bandwidth-block: The bandwidth block (see below). If bandwidth testing is enabled, then bandwidth-block can be used to filter any query.

beacon-type: beacon-type is the equivalent of the Beacon Type filter in the mPulse UI. Use it to filter to a specific beacon source (e.g. page loads). Examples of usage would be beacon-type=page view or beacon-type=manual. Use the following pairs to define the value of the beacon-type parameter for the API:

UI API
Page View page view
JavaScript manual
XHR xhr
Single-Page App spa
Single-Page App (Hard) spa_hard

browser: The browser parameter is the equivalent of the “Browsers” filter in the mPulse UI. Use it to filter to a specific browser version. An example usage would be browser=Chrome/41. The legacy parameter user-agent has the same functionality

browser-family: The browser-family parameter is the equivalent of the “Browser Families” filter in the mPulse UI. Use it to filter to a family of Browsers. An example usage would be browser-family=Chrome

country: The country parameter is specified as the 2-character code; this parameter must be present if region is present.

region: The region parameter is specified as a 2-character code (i.e. a US state or Canadian province); used with country.

connection-type: The connection-type parameter is the equivalent of the “Connection Type” filter in the mPulse UI. Use it to filter data by connection speed (based on IP lookup). An example usage is connection-type=Cellular.

device-type: The device-type parameter is the equivalent of the “Device Type” filter in the mPulse UI. Use it to filter data by device type and compare how users are experiencing your application. An example usage is device-type=Mobile.

device-manufacturer: The device-manufacturer parameter is the equivalent of the “Device Manufacturer” filter in the mPulse UI. Use it to filter data down to the Manufacturer. An example usage is device-manufacturer=Apple.

device-model: The device-model parameter is the equivalent of the “Device Model” filter in the mPulse UI. Use it to filter data down to the Model level of detail. An example usage is device-model=Galaxy S5.

isp: The isp parameter is the equivalent of the “ISP” filter in the mPulse UI. Use it to filter data down to the ISP level of detail. An example usage is isp=Bell Canada.

network-error-code: The network-error-code parameter is the equivalent of the “Network Error” filter in the mPulse UI. Use it to filter data by error for Web XHRs and Mobile apps. An example usage is network-error-code=401. Network-error-code: “.NONE” selects only beacons that did not have the network error code.

*os: The os parameter is the equivalent of the “Operating System” filter in the mPulse UI. Use it to filter data by Operating System. An example usage is os=Windows/7.

os-family: The os-family parameter is the equivalent of the “Operating System Family” filter in the mPulse UI. Use it to filter data by Operating System Family. An example usage is os-family=Windows.

page-group: The page-group parameter is specified as the page group name on the given domain (e.g. where page groups are implemented for a given site use the exact page group’s name).

site-version: The site-version parameter is used to filter data by site version for Mobile apps. An example of ussage is site-version=4.8.2.

custom-dimension: The custom-dimension parameter is used to filter data by custom dimensions created by users in the UI. The syntax is custom-dimension-<label>=VALUE. The label is the custom dimension name with any spaces replaced with the underscore symbol ( _ ) and must only contain lower case letters. An example of usage: custom dimension User Name and value=AlphaDog is custom-dimension-user_name=AlphaDog.

Metric-per-page-load-time Parameters

The metric-per-page-load-time query type has the following additional options by specifying the metric parameter:

Metrics-by-dimension Parameters

For the metrics-by-dimension query type, dimension is a required parameter. Additional options for metrics-by-dimension include:

Bandwidth Parameters

For the bandwidth query type, specify the bandwidth-block parameter using one of the following valid options per request.

For example, the following URL is for the summary data of the “64 – 512 Kbps” bandwidth block:

curl -H "Authentication: <token>" "https://mpulse.soasta.com/concerto/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/bandwidth?date=2013-05-10&bandwidth-block=1"

Date-comparator parameters

Time window support at the API level is provided via the date-comparator.

The possible query type parameter values are identical to those found in the mPulse Dashboard for time window selection. Specify the date-comparator to use by name and then provide its required parameters, if any.

For example, to specify the moving time window for Last Hour: date-comparator=LastHour

Time Window Parameters

The following time window parameters are used whenever using Between or Last.

For example, when specifying a time window using the date-comparator value, Between, use both date-start and date-end.

Some examples of using Between with date-start and date-end parameters are presented below:

?date-comparator=Between&date-start=2013-03-27T00:00:00Z&date-end=2013-03-27T12:00:00Z

OR

?date-comparator=Between&date-start=2013-03-27T00:00:00Z&date-end=2013-03-27T20:00:00Z

OR

?date-comparator=Between&date-start=2013-03-27T12:00:00Z&date-end=2013-03-28T12:00:00Z

When using trailing-seconds, specify the number of seconds to go back. For example, ?date-comparator=Last&trailing-seconds=60.

Response

JSON Response Formats

The default response format for this API is JSON.

All time values are in milliseconds unless noted otherwise.

Query API Response Codes

The Query API uses the following simple response status codes:

Note: If the security token is invalid, HTTP status code “401” (unauthorized) and an empty response will be returned. The token lasts 5 hours, if idle. - 500 (internal error)

Note: If too many API requests are sent within a short amount of time, for the same domain, then the HTTP status code 429 will be returned.

API Rate Limits

For Concurrent API calls, you can use the following formula to find out whether you will hit the concurrent limit: Average Duration (in minutes) = Concurrent Limit / Maximum number of parallel requests For example, if you execute 15 calls per minute and the concurrent limit is 5, then the call duration should be 1/3 minute or less (15 x 1/3 = 5).

Responses by Query Type

Summary Query and Response

Note the time zone for the first example below is UTC while the second is PT.

UTC example:

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/summary?date=2013-05-10"

Will get the response: {"median":"1539","moe":"1410.7486366194114","n":"2520","p95":"13199","p98":"52940"}

Pacific Time example:

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/summary?date=2013-05-10&timezone=US/Pacific"

Will get the response: {"median":"1309","moe":"1568.5234402570175","n":"2264","p95":"12449","p98":"59999"}

Drilldown example:

This last example is a drilldown of summary accomplished by a combination of page group, user agent, and A/B test. The parameters of page group, user agent, and A/B test are in the URL.

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/ummary?date=2013-05-10&page-group=Home&user-agent=Chrome/26&test=B%20Test"

Will get the response: {"median":"1799","moe":"840.5539460033176","n":"15","p95":"3599","p98":"6927"}

Use of Parameter Name Multiple Times example:

This example is to demonstrate the use of a parameter name multiple times, and mix together “family” based parameters, such as os-family, browser-family with os, and browser.

Note: In the previous version (mPulse 55.1.6), the “os-family” and “os” parameters couldn’t be combined.

"summary?page-group=gr1&page-group=gr2&browser-family=chrome&browser=firefox/8.1&date=2015-07-04"

Will get the response that combines data for the page group gr1, page group gr2, all Chrome browsers, and firefox/8.1:

{"median":"7","moe":"0.0","n":"12","p95":"1556","p98":"62504"}

{"median":"8","moe":"0.0","n":"27","p95":"2074","p98":"66671"}

Response status code 400 for invalid parameters example:

This example is to demonstrate the response status code 400 for invalid parameters, such as double question mark ??, which is an error :

"summary??timezone=UTC&isp=Comcast&date=2015-07-04"

Will get the response that displays the status code 400: Error: 400, Bad Request for URL:

https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXX-YYYY-ZZZZ-LVWWW-6U3K2/summary??timezone=UTC&isp=Comcast&date=2015-07-04

Note: In the previous version (mPulse 55.1.6), you had the response status code 500 for invalid parameters.

Histogram Query and Response

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/histogram?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"chartTitle":"Number of Samples","chartTitleSuffix":"null","datasetName":"RumHistogram","reportType":"RumHistogram","resultName":"null","series":{series: [{name: "Number of Samples", aPoints: [{s:150,e:170,c:1},{s:170,e:190,c:1},{s:450000,e:600001,c:2}], kValue: 150, median: 2645, percentile_name: "Median", p95: 9637, p98: 16518, buckets: 134}]}}

Note: In the response, the names ’s’ and 'e’ are start and end times of a bucket. The name 'c’ is the beacon count.

Sessions-per-page-load-time Query and Response

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/sessions-per-page-load-time?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"chartTitle":"Sessions","chartTitleSuffix":"null","datasetName":"RumSessionsPerPageLoadTime","reportType":"RumSessionsPerPageLoadTime","resultName":"null","series":{series: [{"name": "Sessions Per Page Load Time","aPoints": [{"x":250,"y":1},{"x":300,"y":1},{"x":9900,"y":32}],"pointCount":49,"statistics":{"yMin":1.0,"yMax":920.0,"ySum":14886.0,"yAvg":303.8}}]}}

Note: In the response, 'x’ is load time and 'y’ is beacon count.

Metric-per-page-load-time Query and Response

If the optional parameter 'metric’ is not present, then BounceRate is assumed.

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/metric-per-page-load-time?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"chartTitle":"BounceRate","chartTitleSuffix":"null","datasetName":"RumBounceRatePerPageLoadTime","reportType":"RumBounceRatePerPageLoadTime","resultName":"null","series":{"series": [{"name": "Bounce Rate Per Page Load Time","aPoints": [{"x":300,"y":100.0},{"x":550,"y":100.0},{"x":9900,"y":80.7017543859649}],"pointCount":45,"statistics":{"yMin":25.119999999999997,"yMax":100.0,"ySum":2457.9272065997266,"yAvg":54.62}}]}}

In the response, 'x’ is load time and 'y’ is the bounce rate.

The following example is for the custom metric 'DifferentMetric’. Use the 'Metric Analysis’ Dashboard to view the given custom metric on SOASTA’s mPulse dashboard.

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "<mPulse URL>/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/metric-per-page-load-time?date=2013-05-10&metric=DifferentMetric"

Will get the response:

{"chartTitle":"Bounce rate","chartTitleSuffix":null,"datasetName":"RumBounceRatePerPageLoadTime","reportType":"RumBounceRatePerPageLoadTime","resultName":"RumBounceRatePerPageLoadTime", "series":"{series: [{name: \"DifferentMetric\", aPoints: [{x:230,y:0.0},{x:250,y:0.0},{x:300,y:0.0},{x:350,y:0.0},{x:400,y:0.0},{x:450,y:0.0},{x:500,y:0.0},{x:550,y:0.0}, {x:600,y:0.0},{x:700,y:0.0},{x:800,y:0.0},{x:900,y:0.0},{x:1050,y:0.0},{x:1200,y:0.0},{x:1350,y:0.0},{x:1500,y:0.0},{x:1650,y:0.0},{x:1800,y:0.0},{x:1950,y:0.0}, {x:2100,y:0.0},{x:2250,y:0.0},...,{x:9900,y:0.0}],pointCount:52,statistics:{yMin:0.0,yMax:4.9E-324,ySum:0.0,yAvg:0.0}}]}"}

The following example is to show an array in JSON format. The “series” that are part of the response are delivered in the JSON format if the series-format=json parameter is included. Note that in the previous version, series could only be shown as a string.

/metric-per-page-load-time?date=2014-12-09

Will get the following response:

{
      "chartTitle": "BounceRate",
      "chartTitleSuffix": null,
      "datasetName": "RumBounceRatePerPageLoadTime",
      "reportType": "RumBounceRatePerPageLoadTime",
      "resultName": null,
      "series": {
        "name": "BounceRatePerPageLoadTime",
        "aPoints": [
           {
               "x": 65,
               "y": 100
           },
           {
               "x": 80,
               "y": 100
           },
           {
               "x": 85,
               "y": 100
           }
  ],
  "pointCount": 66,
  "statistics": {
       "yMin": 4.061302681992337,
       "yMax": 100,
       "ySum": 3081.9928757927364,
       "yAvg": 46.7
    }
  }
}

By-minute Query and Response

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/by-minute?date=2016-03-26&series-format=json&format=json"

Will get the response: {"chartTitle":"Time in ms","chartTitleSuffix":"per Second","datasetName":"RumPerMinuteLoadTimes","reportType":"RumPerMinuteLoadTimes","resultName":"null","series":{series: [{"name": "Page Load Time","aPoints": [{"x":1458950400000,"y":2489,"label":"","userdata":"Margin of Error: <b>0.582s<\/b>"},{"x":1458950460000,"y":2399,"label":"","userdata":"Margin of Error: <b>0.302s<\/b>"},{"x":1458950520000,"y":2649,"label":"","userdata":"Margin of Error: <b>0.526s<\/b>"},{"x":1458950580000,"y":2549,"label":"","userdata":"Margin of Error: <b>0.587s<\/b>"},{"x":1458950640000,"y":2325,"label":"","userdata":"Margin of Error: <b>1.151s<\/b>"},{"x":1458970920000,"y":3149,"label":"","userdata":"Margin of Error: <b>0.575s<\/b>"},{"x":1459036740000,"y":2349,"label":"","userdata":"Margin of Error: <b>1.122s<\/b>"}],"pointCount":1440,"statistics":{"yMin":1457.0,"yMax":29940.0,"ySum":4242330.0,"yAvg":2946.06}}]}}

In the response, 'x’ is the milliseconds since epoch (Jan. 1, 1970) in the particular time zone. It is the minute on the date. In the same response, 'y’ is the load time by the minute. The time unit is milliseconds.

Geography Query and Response

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/geography?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"data":[{"timerMOE":"1453.667470685991","timerN":"55","timerID":"PageLoad","timerMedian":"3650","country":"A1"},{"timerMOE":"1333.3932830971087","timerN":"117","timerID":"PageLoad","timerMedian":"1843","country":"DE"},{"timerMOE":"1746.9730132707537","timerN":"21","timerID":"PageLoad","timerMedian":"4799","country":"FR"},{"timerMOE":"200.65087910970746","timerN":"201","timerID":"PageLoad","timerMedian":"4414","country":"GB"},{"timerMOE":"3304.547920518942","timerN":"17","timerID":"PageLoad","timerMedian":"4199","country":"GR"},{"timerMOE":"3819.307172703734","timerN":"15","timerID":"PageLoad","timerMedian":"5099","country":"NZ"},{"timerMOE":"25.709062718262405","timerN":"71850","timerID":"PageLoad","timerMedian":"2620","country":"US"},{"timerMOE":"0.0","timerN":"1","timerID":"PageLoad","timerMedian":"6894","country":"IM"}]}

The following two additional examples show drilldowns by country and region. The first example is done for US and Kentucky (KY).

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/geography?date=2016-05-05&country=US&region=KY&series-format=json&format=json"

Will get the response:

{"data":[{"region":"KY","timerMOE":"281.13474231786074","timerN":"633","timerID":"PageLoad","timerMedian":"2890","country":"US"}]}

This second example is for Manchester (MN) in UK (GB).

curl -H "Authentication: e7747ea4ef8de17cf1f85f8a2d2b97ff454f92d3" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/geography?date=2016-05-05&country=GB&region=MN&series-format=json&format=json"

Will get the response:

{"data":[{"region":"MN","timerMOE":"0.0","timerN":"1","timerID":"PageLoad","timerMedian":"2888","country":"GB"}]}

Please refer to the country and region code list provided below for further explanation of using country and region codes with this API.

Page-groups Query and Response

The first example below is for all page groups.

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/page-groups?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"columnNames":["Page Group","Median Time (ms)","MoE (ms)","Measurements","% of total"],"data":[["Sku",3110,"51.53118459097606",17969,"24.388886626762762"],["Search",2344,"37.18436639912604",12789,"17.358198623722465"],["Homepage",3230,"89.01666284827797",11523,"15.639887617574006"],["Cart",2448,"54.92778826088724",4672,"6.341191959498894"],["Orders",1836,"96.4730703867879",3603,"4.890264261574169"],["Checkout",4322,"201.5201582363355",2151,"2.919499979640865"],["(No Page Group)",7199,"3135.7187254718815",4,"0.0054291027050504224"]]}

This second example shows how to drill down by the page group Other…,

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" 'https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/page-groups?date=2013-05-10&page-group=Other...'

And will get the response:

{"columnNames":"[\"Page Group\",\"Median Time (ms)\",\"MoE (ms)\",\"Measurements\"]","data":"[\"[\\\"Other...\\\",\\\"1979\\\",\\\"1832.6238860839994\\\",\\\"1415\\\"]\"]"}

Browsers Query and Response

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/browsers?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"columnNames":["User Agent","Median Time (ms)","MoE (ms)","Measurements","% of total"],"data":[["Chrome/49",2401,"38.08787720482416",24562,"33.337405160362124"],["IE/11",2613,"47.47281503576",17067,"23.164623966773892"],["Firefox/45",2865,"91.168910021261",7163,"9.722165669069044"],["Chrome/43",3391,"182.65375796419997",4355,"5.910935570123648"],["Edge/13",2538,"91.44696849045215",3136,"4.256416520759531"],["Mobile Safari/9",3017,"157.0631248757474",2897,"3.9320276341327687"],["Safari/9",2225,"84.43495242658588",2486,"3.3741873311888377"],["IE/8",3949,"392.5033890947778",179,"0.2429523460510064"],["Opera/29",389286,"759923.7611438242",1,"0.0013572756762626056"],["webOS Browser/3",9407,"0.0",1,"0.0013572756762626056"]]}

Bandwidth Query Type examples

This query curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/bandwidth?date=2016-05-05&series-format=json&format=json"

Will get the response:

{"chartTitle":"Bandwidth Blocks","chartTitleSuffix":"null","datasetName":"RumBandwidth","reportType":"RumBandwidth","resultName":"null","series":{series: [{"name": "Bandwidth Blocks","aPoints": [{"x":"2-6 Mbps","y":2423,"label":"2-6 Mbps"},{"x":"10-100 Mbps","y":1858,"label":"10-100 Mbps"},{"x":"6-10 Mbps","y":1241,"label":"6-10 Mbps"},{"x":"512 Kbps - 2 Mbps","y":628,"label":"512 Kbps - 2 Mbps"},{"x":"64-512 Kbps","y":95,"label":"64-512 Kbps"},{"x":"100-1000 Mbps","y":35,"label":"100-1000 Mbps"},{"x":"More than 1 Gbps","y":28,"label":"More than 1 Gbps"},{"x":"Less than 64 Kbps","y":9,"label":"Less than 64 Kbps"}],"pointCount":8,"statistics":{"yMin":9.0,"yMax":2423.0,"ySum":6317.0,"yAvg":789.63}}]}}

This second example shows how to drilldown by the bandwidth block “Less than 64 Kbps.”,

curl -H "Authentication: da7be4d72030656559f3e41a98924a6b2a544730" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/bandwidth?date=2013-05-10&bandwidth-block=0"

Will get the response:

{"chartTitle":"Bandwidth Blocks","chartTitleSuffix":null,"datasetName":"RumBandwidth","reportType":"RumBandwidth","resultName":"RumBandwidth","series":"{series: [ {name: \"RumBandwidth\", aPoints: [{x:\"Less than 64 Kbps\",y:4,label:\"Less than 64 Kbps\"}],pointCount:1,statistics:{yMin:4.0,yMax:4.0,ySum:4.0,yAvg:4.0}}]}"}

Ab-tests Query and Response

This query curl -H "Authentication: a9568d983584b2858cf34188f5cd285dfe11f6b0" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/ab-tests?date=2016-03-26&series-format=json&format=json"

Will get the response:

{"columnNames":["Test Name","Median Time (ms)","MoE (ms)","Measurements","% of total"],"data":[["Alpha2",2626,"28.316852980853042",60860,"82.60379765734218"],["Beta1",2746,"64.64304616092917",12812,"17.389415964276505"],["Prod",7199,"3135.7187254718815",4,"0.0054291027050504224"],["Beta2",3441,"0.0",1,"0.0013572756762626056"]]}

Timers-metrics Query and Response

This query type is used for navigation timing, custom timers, and custom metrics. The response contains the navigation timing (such as PageLoad, DNS, DomLoad, etc.), up to ten custom timers and up to ten custom metrics that are specified for the domain. For example, if one custom timer is specified as “my timer 1” and two custom metrics are specified as “Conversion Rate” and “Revenue” for the domain soasta.com.

This query curl -H "Authentication: a9568d983584b2858cf34188f5cd285dfe11f6b0" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/timers-metrics?date=2016-03-26&format=json

Will get the response:

{"dataTimeZone":"UTC","values":[{"history":[2489,2399],"id":"PageLoad","latest":2645},{"history":[31,49],"id":"DNS","latest":38},{"history":[1312,1287],"id":"DomLoad","latest":1259},{"history":[2499,2234],"id":"DomReady","latest":2525},{"history":[1264,1199],"id":"FirstByte","latest":1221},{"history":[0,131],"id":"SSL","latest":58},{"history":[999,954],"id":"FirstLastByte","latest":1236},{"history":[31,49],"id":"TCP","latest":37},{"history":[1021,1059],"id":"Network TTLB","latest":1223},{"history":[30,26],"id":"Sessions","latest":19452},{"history":[56,56],"id":"BounceRate","latest":49},{"history":[99,125],"id":"Beacons","latest":73686}]}

Metrics-by-dimension Query and Response

This query curl -H "Authentication: 3c1ddf98e45eb714f9f60d78165181b49f0bbcea" "https://mpulse.soasta.com/concerto/mpulse/api/v2/XXXXX-YYYYY-ZZZZZ-XXXXX-YYYYY/metrics-by-dimension?date=2016-03-26&dimension=country&series-format=json&format=json"

Will get the response:

{"columnNames":["Country","FreePrePaidCard","Orders Placed","Conversion Rate","Add To Basket","Total Order Val"],"data":[["United States",14,0,"0.0",62,0],["Slovakia",62,0,"0.0",23,0],["Germany",66,0,"0.0",50,0],["Austria",3,0,"0.0",5,0],["Ukraine",18,0,"0.0",1,0],["United Kingdom",4,0,"0.0",6,0],["Italy",2,0,"0.0",47,0],["Russia",19,0,"0.0",3,0],["Poland",12,0,"0.0",2,0],["France",7,0,"0.0",1,0]]}

Example Python code for mPulse Query API

Python Example 1: sample.py

######################################
# Sample code using mpulse.py library
# Author: Bilal Al-Shahwany
# Date: 10/2/2014

import mPulse

# Setting mPulse username, password and API Key
username="bal-shahwany@soasta.com"
password="xxx"
APIKey="ZPJEW-ARB6D-HUSS4-X4H6D-2NJLX"

# Initializing instance of mpulse object
mp = mPulse.mPulse(username, password, APIKey)

# Fetching data
print mp.getData('histogram')

metric="summary"
print mp.getData( metric)
print mp.getData( metric+'?date=2014-09-02&page-group=getbird')
print mp.getData( metric+'?date-comparator=Last24Hours&page_group=best')

Python Example 2: mpulse.py

####################################
# Mpulse Webservice Python API
# Author: Bilal Al-Shahwany
# Date: 10/2/2014

import requests
import json

class mPulse:

    # Constructor, will initialize connection to mPulse and call getToken method
     # Param: nPulse username, password and mPulse app API Key
    def __init__(self, username, password, APIKey):
         try:
             self.API = APIKey
             self.token=self.getToken1(username, password)
         except exception, e:
             print "Failed to Initialize mPulse instance ", e.args,str(e)

    # Internal Method for fetching authentication token and storing it in global variable
    # Param: nPulse username, password
    def getToken1(self, username, password):
         try:
              URL = "https://mpulse.soasta.com/concerto/services/rest/RepositoryService/v1/Tokens"
             fp = requests.put(URL, data='{ "userName":"'+username+'", "password":"'+password+'"}')
              js= json.loads(fp.content)
              return js['token']
     except exception, e:
              print "Failed to get Token ", e.args,str(e)

    # Generic data fetching function from mPulse, will return JSON response from the server
    # Param: data keyword (summary, histogram, etc.)
    def getData(self, data):
         try:
           if not "?" in data&colon;
           addFormat="?format=json"
         else:
           addFormat="?format=json"
              URL="https://mpulse.soasta.com/concerto/mpulse/api/v2/"+self.API+"/"+data+addFormat
             fp = requests.get(URL, headers={"Authentication":self.token})
             if fp.status_code<>200:
               return str("Error: "+str(fp.status_code)+", "+fp.reason)
             return fp.content
         except exception, e:
              print "Failed to get data ", e.args,str(e)

Appendix