Insights API Methods

Use the Insights API methods to retrieve analytics data about your Sauce Labs jobs that you can then use to populate a dashboard that is meaningful for your organization.

Refer to Getting Started for Authentication and Server information.

Get Test Results#

GET /v1/analytics/tests

Returns run data for all tests that match the request criteria.

Parameters#

note

This call requires start and end parameters OR the time_range parameter.

start

| QUERY | REQUIRED | DATE |

The starting date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

end

| QUERY | REQUIRED | DATE |

The ending date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

time_range

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time backward from the current time representing the period during which the test runs executed. Acceptable units include d (day); h (hour); m (minute); s (second).

scope

| QUERY | OPTIONAL | STRING |

Specifies the scope of the owner parameter. Supported values are:

  • me - owner is the logged-in requestor.
  • organization - owner is all users the logged-in requestor's organization.
  • single - owner is one or more users in logged-in requestor's organization. Setting this value makes the owner parameter required.

owner

| QUERY | OPTIONAL | ARRAY of STRINGS |

The name of one or more users in the requestor's organization who executed the requested tests. This parameter is required if the scope parameter is set to single.

status

| QUERY | OPTIONAL | STRING |

Limit results to only those with a specified status. Supported values are:

  • passed
  • errored
  • failed
  • complete

build

| QUERY | OPTIONAL | STRING |

Limit results to those grouped by this build name.

from

| QUERY | OPTIONAL | INTEGER |

Begin results list from this record number.

mainDocumentTransferSize

| QUERY | OPTIONAL | INTEGER |

The maximum number of results to return.

missing_build

| QUERY | OPTIONAL | INCLUDE |

Requires no value. If this parameter is included in the query string, results will only include tests with no assigned build.

query

| QUERY | OPTIONAL | STRING |

Limit results to only those with this test name.

desc

| QUERY | OPTIONAL | BOOLEAN |

Set to true to sort results in descending order by creation time. Default value is false.

error

| QUERY | OPTIONAL | STRING |

Limit results to only those that threw this error message.

Sample Request
curl --location --request GET "https://api.us-west-1.saucelabs.com/v1/analytics/tests?start=2017-03-01T12:00:00Z&end=2017-03-02T12:00:00Z&size=10&from=10&build=build-123"
--header 'Authorization: Basic $SAUCE_USERNAME:$SAUCE_ACCESS_KEY' \
--data-raw ''

Responses#

200Success.
400Bad Request. May include additional error message, such as "start and end parameters are required."
404Not found.
Sample Response
{
"meta": {
"status": 200
},
"items": [
{
"id": "50fdd2369eer3031ad912kib57b12440",
"owner": "USERNAME",
"ancestor": "USERNAME",
"name": "TestGet",
"build": "build-123",
"creation_time": "2017-03-01T12:13:39Z",
"end_time": "2017-03-01T12:16:22Z",
"status": "complete",
"error": "",
"os": "OS X El Capitan (10.11)",
"browser": "iPhone 10.0",
"details_url": "https://saucelabs.com/rest/v1.1/a-team/jobs/50fdd2369eer3031ad912kib57b12440"
},
// 9 more tests
],
"has_more": true
}

Get Summary of Test Metrics#

GET /v1/analytics/insights/test-metrics

Returns an aggregate of metric values for runs of a specified test during the specified time period.

Parameters#

note

This call requires start and end parameters OR the time_range parameter.

start

| QUERY | REQUIRED | DATE |

The starting date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

end

| QUERY | REQUIRED | DATE |

The ending date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

time_range

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time backward from the current time representing the period during which the test runs executed. Acceptable units include d (day); h (hour); m (minute); s (second).

scope

| QUERY | OPTIONAL | STRING |

Specifies the scope of the owner parameter. Supported values are:

  • me - owner is the logged-in requestor.
  • organization - owner is all users the logged-in requestor's organization.
  • single - owner is one or more users in logged-in requestor's organization. Setting this value makes the owner parameter required.

owner

| QUERY | OPTIONAL | ARRAY of STRINGS |

The name of one or more users in the requestor's organization who executed the requested tests. This parameter is required if the scope parameter is set to single.

status

| QUERY | OPTIONAL | STRING |

Limit results to only those with a specified status. Supported values are:

  • passed
  • errored
  • failed
  • complete

query

| QUERY | REQUIRED | STRING |

The name of the test for which results are requested.

os

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified operating systems.

browser

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified browsers.

Sample Request
curl --location --request GET "https://api.us-west-1.saucelabs.com/v1/analytics/insights/test-metrics?start=1515687172&end=1516291972&query=AnalyticsSeleniumTest%20on%20OS%20X%2010.10"
--header 'Authorization: Basic $SAUCE_USERNAME:$SAUCE_ACCESS_KEY' \
--data-raw ''

Responses#

200Success.
400Bad Request. May include additional error message, such as "start and end parameters are required."
404Not found.
Sample Response
{
"meta": {
"status": 200
},
"aggs": {
"count": 1008,
"fastestRun": {
"id": "1cc127f6af024184a45fc45817672a341",
"owner": "a-team",
"ancestor": "a-team",
"name": "AnalyticsSeleniumTest on OS X 10.10",
"build": "",
"creation_time": "2018-01-12T11:50:02Z",
"start_time": "2018-01-12T11:50:02Z",
"end_time": "2018-01-12T11:50:27Z",
"duration": 25,
"status": "passed",
"error": "",
"os": "OS X Yosemite (10.10)",
"os_normalized": "",
"browser": "Chrome 51.0",
"browser_normalized": "",
"details_url": "https://saucelabs.com/rest/v1.1/a-team/jobs/1cc127f6af024184a45fc45817672a341"
},
"slowestRun": {
"id": "faf35305919245ebaceab93712d009b0",
"owner": "a-team",
"ancestor": "a-team",
"name": "AnalyticsSeleniumTest on OS X 10.10",
"build": "",
"creation_time": "2018-01-15T19:10:01Z",
"start_time": "2018-01-15T19:10:01Z",
"end_time": "2018-01-15T19:40:59Z",
"duration": 1858,
"status": "errored",
"error": "Test exceeded maximum duration after 1800 seconds",
"os": "OS X Yosemite (10.10)",
"os_normalized": "",
"browser": "Chrome 51.0",
"browser_normalized": "",
"details_url": "https://saucelabs.com/rest/v1.1/a-team/jobs/faf35305919245ebaceab93712d009b0"
},
"statuses": {
"errored": 7,
"failed": 1,
"passed": 1000
},
"totalQueueTime": 0.3843098311817279,
"totalRunTime": 33.18867924528302
}
}

Get Test Trends#

GET /v1/analytics/trends/tests

Returns a set of data "buckets" representing tests that were run in each time interval defined by the request parameters.

Parameters#

note

This call requires start and end parameters OR the time_range parameter.

start

| QUERY | REQUIRED | DATE |

The starting date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

end

| QUERY | REQUIRED | DATE |

The ending date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

time_range

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time backward from the current time representing the period during which the test runs executed. Acceptable units include d (day); h (hour); m (minute); s (second).

scope

| QUERY | OPTIONAL | STRING |

Specifies the scope of the owner parameter. Supported values are:

  • me - owner is the logged-in requestor.
  • organization - owner is all users the logged-in requestor's organization.
  • single - owner is one or more users in logged-in requestor's organization. Setting this value makes the owner parameter required.

owner

| QUERY | OPTIONAL | ARRAY of STRINGS |

The name of one or more users in the requestor's organization who executed the requested tests. This parameter is required if the scope parameter is set to single.

status

| QUERY | OPTIONAL | STRING |

Limit results to only those with a specified status. Supported values are:

  • passed
  • errored
  • failed
  • complete

interval

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time representing the boundary of each data bucket. Acceptable units include d (day); h (hour); m (minute); s (second).

os

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified operating systems.

browser

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified browsers.

Sample Request
curl --location --request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/tests?interval=1h&start=2017-03-01T12:00:00Z&end=2017-03-02T12:00:00Z&os=Linux"
--header 'Authorization: Basic $SAUCE_USERNAME:$SAUCE_ACCESS_KEY' \
--data-raw ''

Responses#

200Success.
400Bad Request. May include additional error message, such as "start and end parameters are required."
404Not found.
Sample Response
{
"meta": {
"status": 200
},
"buckets": [
{
"timestamp": "2017-03-09T12:00:00.000Z",
"count": 204,
"aggs": {
"os": [
{
"name": "OS X El Capitan (10.11)",
"count": 98
},
{
"name": "Windows 7",
"count": 65
},
{
"name": "Linux",
"count": 41
}
],
"owner": [
{
"name": "a-team",
"count": 204
}
],
"status": [
{
"name": "complete",
"count": 133
},
{
"name": "passed",
"count": 58
},
{
"name": "failed",
"count": 12
},
{
"name": "errored",
"count": 1
}
]
}
},
// more buckets...
],
"metrics": {
"os": {
"Linux": 163,
"OS X El Capitan (10.11)": 356,
"Windows 7": 229
},
"owner": {
"a-team": 748
},
"status": {
"complete": 496,
"errored": 2,
"failed": 44,
"passed": 206
}
}
}

Get Builds and Tests#

GET /v1/analytics/trends/builds_tests

Returns the set of all tests run within the specified time period, grouped by whether each test was part of a build or not.

Parameters#

note

This call requires start and end parameters OR the time_range parameter.

start

| QUERY | REQUIRED | DATE |

The starting date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

end

| QUERY | REQUIRED | DATE |

The ending date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

time_range

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time backward from the current time representing the period during which the test runs executed. Acceptable units include d (day); h (hour); m (minute); s (second).

scope

| QUERY | OPTIONAL | STRING |

Specifies the scope of the owner parameter. Supported values are:

  • me - owner is the logged-in requestor.
  • organization - owner is all users the logged-in requestor's organization.
  • single - owner is one or more users in logged-in requestor's organization. Setting this value makes the owner parameter required.

owner

| QUERY | OPTIONAL | ARRAY of STRINGS |

The name of one or more users in the requestor's organization who executed the requested tests. This parameter is required if the scope parameter is set to single.

status

| QUERY | OPTIONAL | STRING |

Limit results to only those with a specified status. Supported values are:

  • passed
  • errored
  • failed
  • complete

os

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified operating systems.

browser

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified browsers.

Sample Request
curl --location --request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/builds_tests?start=2017-03-01T12:00:00Z&end=2017-03-02T12:00:00Z"
--header 'Authorization: Basic $SAUCE_USERNAME:$SAUCE_ACCESS_KEY' \
--data-raw ''

Responses#

200Success.
400Bad Request. May include additional error message, such as "start and end parameters are required."
404Not found.
Sample Response
{
"meta": {
"status": 200
},
"builds": {
"items": [
{
"name": "build-123",
"tests_count": 34,
"duration": 1916,
"start_time": "2017-03-01T12:09:16Z",
"end_time": "2017-03-01T12:41:25Z",
"tests": [
{
"id": "a1a2b38812hy42e5affbd54p9757re5t",
"owner": "USERNAME",
"ancestor": "USERNAME",
"name": "TestStatus",
"creation_time": "2017-03-01T12:09:16Z",
"end_time": "2017-03-01T12:10:44Z",
"status": "failed",
"error": "",
"os": "Linux",
"browser": "Android 5.1",
"details_url": "https://saucelabs.com/rest/v1.1/a-team/jobs/a1a2b38812hy42e5affbd54p9757re5t"
},
// up to 10 items
],
"has_more": true,
"aggs": {
"status": [
{
"name": "complete",
"count": 23
},
{
"name": "passed",
"count": 9
},
{
"name": "failed",
"count": 2
}
]
}
},
// up to 25 builds
],
"has_more": true
},
"tests_missing_build": {
"items": [],
"has_more": false
}
}

Get Error Trends#

GET /v1/analytics/trends/errors

Returns an array of errors that occurred on all tests run within the specified time period.

Parameters#

note

This call requires start and end parameters OR the time_range parameter.

start

| QUERY | REQUIRED | DATE |

The starting date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

end

| QUERY | REQUIRED | DATE |

The ending date of the period during which the test runs executed, in YYY-MM-DDTHH:MM:SSZ or Unix time format.

time_range

| QUERY | REQUIRED | DURATION + UNIT |

The amount of time backward from the current time representing the period during which the test runs executed. Acceptable units include d (day); h (hour); m (minute); s (second).

scope

| QUERY | OPTIONAL | STRING |

Specifies the scope of the owner parameter. Supported values are:

  • me - owner is the logged-in requestor.
  • organization - owner is all users the logged-in requestor's organization.
  • single - owner is one or more users in logged-in requestor's organization. Setting this value makes the owner parameter required.

owner

| QUERY | OPTIONAL | ARRAY of STRINGS |

The name of one or more users in the requestor's organization who executed the requested tests. This parameter is required if the scope parameter is set to single.

status

| QUERY | OPTIONAL | STRING |

Limit results to only those with a specified status. Supported values are:

  • passed
  • errored
  • failed
  • complete

os

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified operating systems.

browser

| QUERY | OPTIONAL | ARRAY OF STRINGS |

Limit results to only those run on the specified browsers.

Sample Request
curl --location --request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/errors?start=2017-03-01T12:00:00Z&end=2017-03-02T12:00:00Z&scope=organization"
--header 'Authorization: Basic $SAUCE_USERNAME:$SAUCE_ACCESS_KEY' \
--data-raw ''

Responses#

200Success.
400Bad Request. May include additional error message, such as "start and end parameters are required."
404Not found.
Sample Response
{
"meta": {
"status": 200
},
"buckets": [
{
"name": "Selenium didn't complete your last command on time.\nFor help, please check https://wiki.saucelabs.com/display/DOCS/Common+Error+Messages",
"count": 1,
"items": [
{
"id": "8f5nf6370061122bb6ah4ee10a2c966d",
"owner": "USERNAME",
"ancestor": "USERNAME",
"name": "TestScreenshot",
"creation_time": "2017-03-01T17:47:35Z",
"end_time": "2017-03-01T17:54:03Z",
"status": "errored",
"error": "Selenium didn't complete your last command on time.\nFor help, please check https://wiki.saucelabs.com/display/DOCS/Common+Error+Messages",
"os": "Linux",
"browser": "Android 5.1",
"details_url": "https://saucelabs.com/rest/v1.1/USERNAME/jobs/8f5nf6370061122bb6ah4ee10a2c966d"
}
],
"has_more": false
},
// more errors...
]
}

Last updated on by Nancy Sweeney