Share via

Runs - Query

Service:
Test
API Version:
7.1

Query Test Runs based on filters. Mandatory fields are minLastUpdatedDate and maxLastUpdatedDate.

GET https://dev.azure.com/{organization}/{project}/_apis/test/runs?minLastUpdatedDate={minLastUpdatedDate}&maxLastUpdatedDate={maxLastUpdatedDate}&api-version=7.1
With optional parameters: 
GET https://dev.azure.com/{organization}/{project}/_apis/test/runs?minLastUpdatedDate={minLastUpdatedDate}&maxLastUpdatedDate={maxLastUpdatedDate}&state={state}&planIds={planIds}&isAutomated={isAutomated}&publishContext={publishContext}&buildIds={buildIds}&buildDefIds={buildDefIds}&branchName={branchName}&releaseIds={releaseIds}&releaseDefIds={releaseDefIds}&releaseEnvIds={releaseEnvIds}&releaseEnvDefIds={releaseEnvDefIds}&runTitle={runTitle}&$top={$top}&continuationToken={continuationToken}&api-version=7.1

URI Parameters

Name In Required Type Description
organization
 path True

string

The name of the Azure DevOps organization.
project
 path True

string

Project ID or project name
api-version
 query True

string

Version of the API to use. This should be set to '7.1' to use this version of the api.
maxLastUpdatedDate
 query True

string (date-time)

Maximum Last Modified Date of run to be queried (Mandatory, difference between min and max date can be atmost 7 days).
minLastUpdatedDate
 query True

string (date-time)

Minimum Last Modified Date of run to be queried (Mandatory).
$top
 query

integer (int32)

Number of runs to be queried. Limit is 100
branchName
 query

string

Source Branch name of the Runs to be queried.
buildDefIds
 query

string (array (int32))

Build Definition Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
buildIds
 query

string (array (int32))

Build Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
continuationToken
 query

string

continuationToken received from previous batch or null for first batch. It is not supposed to be created (or altered, if received from last batch) by user.
isAutomated
 query

boolean

Automation type of the Runs to be queried.
planIds
 query

string (array (int32))

Plan Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
publishContext
 query

TestRunPublishContext

PublishContext of the Runs to be queried.
releaseDefIds
 query

string (array (int32))

Release Definition Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
releaseEnvDefIds
 query

string (array (int32))

Release Environment Definition Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
releaseEnvIds
 query

string (array (int32))

Release Environment Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
releaseIds
 query

string (array (int32))

Release Ids of the Runs to be queried, comma separated list of valid ids (limit no. of ids 10).
runTitle
 query

string

Run Title of the Runs to be queried.
state
 query

TestRunState

Current state of the Runs to be queried.

Responses

Name Type Description
200 OK

TestRun[]

successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name Description
vso.test Grants the ability to read test plans, cases, results and other test management related artifacts.

Definitions

Name Description
BuildConfiguration

BuildConfiguration Details.
CustomTestField

A custom field information. Allowed Key : Value pairs - ( AttemptId: int value, IsTestResultFlaky: bool)
DtlEnvironmentDetails

This is a temporary class to provide the details for the test run environment.
IdentityRef
JobReference

Job in pipeline. This is related to matrixing in YAML.
PhaseReference

Phase in pipeline
PipelineReference

Pipeline reference
ReferenceLinks

The class to represent a collection of REST reference links.
ReleaseReference

Reference to a release.
ResultMetadata

ResultMetadata for the given outcome/count.
RunFilter

This class is used to provide the filters used for discovery
RunStatistic

Test run statistics per outcome.
ShallowReference

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.
StageReference

Stage in pipeline
TestEnvironment

Test environment Detail.
TestResolutionState

Test Resolution State Details.
TestRun

Test run details.
TestRunPublishContext

PublishContext of the Runs to be queried.
TestRunState
TestRunSubstate

The types of sub states for test run.
TestTag

Tag attached to a run or result.

BuildConfiguration

Object

BuildConfiguration Details.

Name Type Description
branchName

string

Branch name for which build is generated.
buildDefinitionId

integer (int32)

BuildDefinitionId for build.
buildSystem

string

Build system.
creationDate

string (date-time)

Build Creation Date.
flavor

string

Build flavor (eg Build/Release).
id

integer (int32)

BuildConfiguration Id.
number

string

Build Number.
platform

string

BuildConfiguration Platform.
project

ShallowReference

Project associated with this BuildConfiguration.
repositoryGuid

string

Repository Guid for the Build.
repositoryType

string

Repository Type (eg. TFSGit).
sourceVersion

string

Source Version(/first commit) for the build was triggered.
targetBranchName

string

Target BranchName.
uri

string

Build Uri.

CustomTestField

Object

A custom field information. Allowed Key : Value pairs - ( AttemptId: int value, IsTestResultFlaky: bool)

Name Type Description
fieldName

string

Field Name.
value

object

Field value.

DtlEnvironmentDetails

Object

This is a temporary class to provide the details for the test run environment.

Name Type Description
csmContent

string

csmParameters

string

subscriptionName

string

IdentityRef

Object
Name Type Description
_links

ReferenceLinks

This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor

string

The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias

string

Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName

string

This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id

string

imageUrl

string

Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive

boolean

Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity

boolean

Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer

boolean

Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin

boolean

profileUrl

string

Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName

string

Deprecated - use Domain+PrincipalName instead
url

string

This url is the full route to the source resource of this graph subject.

JobReference

Object

Job in pipeline. This is related to matrixing in YAML.

Name Type Description
attempt

integer (int32)

Attempt number of the job
jobName

string

Matrixing in YAML generates copies of a job with different inputs in matrix. JobName is the name of those input. Maximum supported length for name is 256 character.

PhaseReference

Object

Phase in pipeline

Name Type Description
attempt

integer (int32)

Attempt number of the phase
phaseName

string

Name of the phase. Maximum supported length for name is 256 character.

PipelineReference

Object

Pipeline reference

Name Type Description
jobReference

JobReference

Reference of the job
phaseReference

PhaseReference

Reference of the phase.
pipelineId

integer (int32)

Reference of the pipeline with which this pipeline instance is related.
stageReference

StageReference

Reference of the stage.
Object

The class to represent a collection of REST reference links.

Name Type Description
links

object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

ReleaseReference

Object

Reference to a release.

Name Type Description
attempt

integer (int32)

Number of Release Attempt.
creationDate

string (date-time)

Release Creation Date(UTC).
definitionId

integer (int32)

Release definition ID.
environmentCreationDate

string (date-time)

Environment creation Date(UTC).
environmentDefinitionId

integer (int32)

Release environment definition ID.
environmentDefinitionName

string

Release environment definition name.
environmentId

integer (int32)

Release environment ID.
environmentName

string

Release environment name.
id

integer (int32)

Release ID.
name

string

Release name.

ResultMetadata

Enumeration

ResultMetadata for the given outcome/count.

Value Description
rerun

Rerun metadata
flaky

Flaky metadata

RunFilter

Object

This class is used to provide the filters used for discovery

Name Type Description
sourceFilter

string

filter for the test case sources (test containers)
testCaseFilter

string

filter for the test cases

RunStatistic

Object

Test run statistics per outcome.

Name Type Description
count

integer (int32)

Test result count fo the given outcome.
outcome

string

Test result outcome
resolutionState

TestResolutionState

Test run Resolution State.
resultMetadata

ResultMetadata

ResultMetadata for the given outcome/count.
state

string

State of the test run

ShallowReference

Object

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.

Name Type Description
id

string

ID of the resource
name

string

Name of the linked resource (definition name, controller name, etc.)
url

string

Full http link to the resource

StageReference

Object

Stage in pipeline

Name Type Description
attempt

integer (int32)

Attempt number of stage
stageName

string

Name of the stage. Maximum supported length for name is 256 character.

TestEnvironment

Object

Test environment Detail.

Name Type Description
environmentId

string (uuid)

Test Environment Id.
environmentName

string

Test Environment Name.

TestResolutionState

Object

Test Resolution State Details.

Name Type Description
id

integer (int32)

Test Resolution state Id.
name

string

Test Resolution State Name.
project

ShallowReference

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.

TestRun

Object

Test run details.

Name Type Description
build

ShallowReference

Build associated with this test run.
buildConfiguration

BuildConfiguration

Build configuration details associated with this test run.
comment

string

Comments entered by those analyzing the run.
completedDate

string (date-time)

Completed date time of the run.
controller

string

Test Run Controller.
createdDate

string (date-time)

Test Run CreatedDate.
customFields

CustomTestField[]

List of Custom Fields for TestRun.
dropLocation

string

Drop Location for the test Run.
dtlAutEnvironment

ShallowReference

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.
dtlEnvironment

ShallowReference

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.
dtlEnvironmentCreationDetails

DtlEnvironmentDetails

This is a temporary class to provide the details for the test run environment.
dueDate

string (date-time)

Due date and time for test run.
errorMessage

string

Error message associated with the run.
filter

RunFilter

This class is used to provide the filters used for discovery
id

integer (int32)

ID of the test run.
incompleteTests

integer (int32)

Number of Incomplete Tests.
isAutomated

boolean

true if test run is automated, false otherwise.
iteration

string

The iteration to which the run belongs.
lastUpdatedBy

IdentityRef

Team foundation ID of the last updated the test run.
lastUpdatedDate

string (date-time)

Last updated date and time
name

string

Name of the test run.
notApplicableTests

integer (int32)

Number of Not Applicable Tests.
owner

IdentityRef

Team Foundation ID of the owner of the runs.
passedTests

integer (int32)

Number of passed tests in the run
phase

string

Phase/State for the testRun.
pipelineReference

PipelineReference

Reference of the pipeline to which this test run belongs.
plan

ShallowReference

Test plan associated with this test run.
postProcessState

string

Post Process State.
project

ShallowReference

Project associated with this run.
release

ReleaseReference

Release Reference for the Test Run.
releaseEnvironmentUri

string

Release Environment Uri for TestRun.
releaseUri

string

Release Uri for TestRun.
revision

integer (int32)

runStatistics

RunStatistic[]

RunSummary by outcome.
startedDate

string (date-time)

Start date time of the run.
state

string

The state of the run. Type TestRunState Valid states - Unspecified ,NotStarted, InProgress, Completed, Waiting, Aborted, NeedsInvestigation
substate

TestRunSubstate

TestRun Substate.
tags

TestTag[]

Tags attached with this test run.
testEnvironment

TestEnvironment

Test environment associated with the run.
testMessageLogId

integer (int32)

testSettings

ShallowReference

An abstracted reference to some other resource. This class is used to provide the build data contracts with a uniform way to reference other resources in a way that provides easy traversal through links.
totalTests

integer (int32)

Total tests in the run
unanalyzedTests

integer (int32)

Number of failed tests in the run.
url

string

Url of the test run
webAccessUrl

string

Web Access Url for TestRun.

TestRunPublishContext

Enumeration

PublishContext of the Runs to be queried.

Value Description
build

Run is published for Build Context.
release

Run is published for Release Context.
all

Run is published for any Context.

TestRunState

Enumeration
Value Description
unspecified

Only used during an update to preserve the existing value.
notStarted

The run is still being created. No tests have started yet.
inProgress

Tests are running.
completed

All tests have completed or been skipped.
aborted

Run is stopped and remaining tests have been aborted
waiting

Run is currently initializing This is a legacy state and should not be used any more
needsInvestigation

Run requires investigation because of a test point failure This is a legacy state and should not be used any more

TestRunSubstate

Enumeration

The types of sub states for test run.

Value Description
none

Run with noState.
creatingEnvironment

Run state while Creating Environment.
runningTests

Run state while Running Tests.
canceledByUser

Run state while Creating Environment.
abortedBySystem

Run state when it is Aborted By the System.
timedOut

Run state when run has timedOut.
pendingAnalysis

Run state while Pending Analysis.
analyzed

Run state after being Analysed.
cancellationInProgress

Run state when cancellation is in Progress.

TestTag

Object

Tag attached to a run or result.

Name Type Description
name

string

Name of the tag, alphanumeric value less than 30 chars