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

timePrecision
query
  • boolean

Whether or not to use time precision.

$top
query
  • integer
int32

The max number of results to return.

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.

Request Body

Name Type Description
query
  • string

The text of the WIQL query

Responses

Name Type Description
200 OK

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

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

The source work item.

target

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

The columns of the query.

queryResultType

The result type

queryType

The type of the query

sortColumns

The sort columns of the query.

workItemRelations

The work item links returned by the query.

workItems

The work items returned by the query.

WorkItemQuerySortColumn

A sort column.

Name Type Description
descending
  • boolean

The direction to sort by.

field

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