Wiql - Query By Wiql

Gets the results of the query given its WIQL.

POST https://dev.azure.com/{organization}/{project}/{team}/_apis/wit/wiql?api-version=5.0
POST https://dev.azure.com/{organization}/{project}/{team}/_apis/wit/wiql?timePrecision={timePrecision}&$top={$top}&api-version=5.0

URI Parameters

Name In Required Type Description
organization
path True

string

The name of the Azure DevOps organization.

project
path

string

Project ID or project name

team
path

string

Team ID or team name

api-version
query True

string

Version of the API to use. This should be set to '5.0' to use this version of the api.

$top
query

integer

int32

The max number of results to return.

timePrecision
query

boolean

Whether or not to use time precision.

Request Body

Name Type Description
query

string

The text of the WIQL query

Responses

Name Type Description
200 OK

WorkItemQueryResult

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.work Grants the ability to read work items, queries, boards, area and iterations paths, and other work item tracking related metadata. Also grants the ability to execute queries, search work items and to receive notifications about work item events via service hooks.

Examples

Get results of a flat work item query.

Sample request

POST https://dev.azure.com/fabrikam/_apis/wit/wiql?api-version=5.0

{
  "query": "Select [System.Id], [System.Title], [System.State] From WorkItems Where [System.WorkItemType] = 'Task' AND [State] <> 'Closed' AND [State] <> 'Removed' order by [Microsoft.VSTS.Common.Priority] asc, [System.CreatedDate] desc"
}

Sample response

{
  "queryType": "flat",
  "asOf": "2014-12-29T20:49:34.617Z",
  "columns": [
    {
      "referenceName": "System.Id",
      "name": "ID",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Id"
    },
    {
      "referenceName": "System.Title",
      "name": "Title",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Title"
    },
    {
      "referenceName": "System.State",
      "name": "State",
      "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.State"
    }
  ],
  "sortColumns": [
    {
      "field": {
        "referenceName": "Microsoft.VSTS.Common.Priority",
        "name": "Priority",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/Microsoft.VSTS.Common.Priority"
      },
      "descending": false
    },
    {
      "field": {
        "referenceName": "System.CreatedDate",
        "name": "Created Date",
        "url": "https://dev.azure.com/fabrikam/_apis/wit/fields/System.CreatedDate"
      },
      "descending": true
    }
  ],
  "workItems": [
    {
      "id": 300,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/300"
    },
    {
      "id": 299,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/299"
    },
    {
      "id": 298,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/298"
    },
    {
      "id": 17,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/17"
    },
    {
      "id": 16,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/16"
    },
    {
      "id": 15,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/15"
    },
    {
      "id": 14,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/14"
    },
    {
      "id": 9,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/9"
    },
    {
      "id": 8,
      "url": "https://dev.azure.com/fabrikam/_apis/wit/workItems/8"
    }
  ]
}

Definitions

Name Description
QueryResultType

The result type

QueryType

The type of query.

Wiql

A WIQL query

WorkItemFieldReference

Reference to a field in a work item

WorkItemLink

A link between two work items.

WorkItemQueryResult

The result of a work item query.

WorkItemQuerySortColumn

A sort column.

WorkItemReference

Contains reference to a work item.

QueryResultType

The result type

Name Type Description
workItem

string

A list of work items (for flat queries).

workItemLink

string

A list of work item links (for OneHop and Tree queries).

QueryType

The type of query.

Name Type Description
flat

string

Gets a flat list of work items.

oneHop

string

Gets a list of work items and their direct links.

tree

string

Gets a tree of work items showing their link hierarchy.

Wiql

A WIQL query

Name Type Description
query

string

The text of the WIQL query

WorkItemFieldReference

Reference to a field in a work item

Name Type Description
name

string

The name of the field.

referenceName

string

The reference name of the field.

url

string

The REST URL of the resource.

A link between two work items.

Name Type Description
rel

string

The type of link.

source

WorkItemReference

The source work item.

target

WorkItemReference

The target work item.

WorkItemQueryResult

The result of a work item query.

Name Type Description
asOf

string

The date the query was run in the context of.

columns

WorkItemFieldReference[]

The columns of the query.

queryResultType

QueryResultType

The result type

queryType

QueryType

The type of the query

sortColumns

WorkItemQuerySortColumn[]

The sort columns of the query.

workItemRelations

WorkItemLink[]

The work item links returned by the query.

workItems

WorkItemReference[]

The work items returned by the query.

WorkItemQuerySortColumn

A sort column.

Name Type Description
descending

boolean

The direction to sort by.

field

WorkItemFieldReference

A work item field.

WorkItemReference

Contains reference to a work item.

Name Type Description
id

integer

Work item ID.

url

string

REST API URL of the resource