Skip to main content

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 -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \--request GET "https://api.us-west-1.saucelabs.com/v1/analytics/tests?start=2021-05-01T12:00:00Z&end=2021-05-02T12:00:00Z&size=10&from=10&build=build-123" | json_pp

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 -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --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" | json_pp

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 -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \--request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/tests?interval=1h&start=2021-05-01T12:00:00Z&end=2021-05-02T12:00:00Z&os=Linux" | json_pp

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 -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \--request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/builds_tests?start=2021-05-01T12:00:00Z&end=2021-05-02T12:00:00Z" |json_pp

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 -u "$SAUCE_USERNAME:$SAUCE_ACCESS_KEY" --location \--request GET "https://api.us-west-1.saucelabs.com/v1/analytics/trends/errors?start=2021-05-01T12:00:00Z&end=2021-05-02T12:00:00Z&scope=organization" | json_pp

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://docs.saucelabs.com/dev/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://docs.saucelabs.com/dev/error-messages",          "os": "Linux",          "browser": "Android 5.1",          "details_url": "https://saucelabs.com/rest/v1.1/USERNAME/jobs/8f5nf6370061122bb6ah4ee10a2c966d"        }      ],      "has_more": false    },    // more errors...  ]}