# List Builds — Azure DevOps

> List a project's builds, optionally filtered by definition, status, result, branch or time window. Returns each build's id, number, status, result and triggering commit. Use this to report on CI health or to find the last successful build…

- Key: `azure_devops-list-builds`
- Type: Action (Read-only)
- Version: 0.0.2
- App: Azure DevOps (`azure_devops`) — https://pipedream.com/apps/azure-devops.md
- This page (HTML): https://pipedream.com/apps/azure-devops/actions/list-builds
- Hints: read-only · open-world
- Source: https://github.com/PipedreamHQ/pipedream/blob/master/components/azure_devops/actions/list-builds/list-builds.mjs

## Description

List a project's builds, optionally filtered by definition, status, result, branch or time window. Returns each build's id, number, status, result and triggering commit. Use this to report on CI health or to find the last successful build of a branch. Example: result `failed` on branch `refs/heads/main`. [See the documentation](https://learn.microsoft.com/en-us/rest/api/azure/devops/build/builds/list?view=azure-devops-rest-7.1)

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `organization` | `string` | Yes | Name of the organization Options are loaded from the connected account. |
| `project` | `string` | Yes | Project ID or project name. Run the List Projects action first to obtain valid values. |
| `definitionIds` | `string[]` | No | Only return builds for these definition IDs. Run the List Build Definitions action first to obtain valid values. |
| `statusFilter` | `string` | No | Only return builds in this status |
| `resultFilter` | `string` | No | Only return builds with this result |
| `branchName` | `string` | No | Only return builds that ran on this fully qualified branch name, e.g. refs/heads/main |
| `queryOrder` | `string` | No | Order the results are returned in |
| `minTime` | `string` | No | Only return builds after this date, e.g. 2026-01-01T00:00:00Z. Interpreted against the field named by Query Order. |
| `maxTime` | `string` | No | Only return builds before this date, e.g. 2026-01-31T00:00:00Z. Interpreted against the field named by Query Order. |
| `limit` | `integer` | No | Maximum number of builds to return (1-1000) |
| `buildIds` | `string[]` | No | Only return these build IDs, e.g. ["4821", "4822"]. Run the List Builds action first to obtain valid values. |
| `buildNumber` | `string` | No | Only return builds matching this build number. Append * for a prefix search, e.g. 20260820.* |
| `reasonFilter` | `string` | No | Only return builds started for this reason |
| `requestedFor` | `string` | No | Only return builds requested by this identity GUID, e.g. d6245f20-2af8-44f4-9451-8107cb2767db. Run the List Users action first to obtain valid values. |
| `repositoryId` | `string` | No | Only return builds from this repository. Requires Repository Type. Run the List Repositories action first to obtain valid values. |
| `repositoryType` | `string` | No | Type of the repository named in Repository, e.g. TfsGit, GitHub |
| `tagFilters` | `string[]` | No | Only return builds carrying all of these tags |
| `properties` | `string[]` | No | Extended property names to return with each build |
| `queues` | `string[]` | No | Only return builds that ran on these agent queue IDs, e.g. ["9"]. Queue IDs appear as queue.id on any build this action returns. |
| `maxBuildsPerDefinition` | `integer` | No | Cap how many builds are returned for each definition |
| `deletedFilter` | `string` | No | Whether to exclude, include or only return deleted builds. Defaults to excludeDeleted. |

## Run it

**MCP**

```ts
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const accessToken = await pd.rawAccessToken

const transport = new StreamableHTTPClientTransport(
  new URL("https://remote.mcp.pipedream.net/v3"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "x-pd-project-id": process.env.PIPEDREAM_PROJECT_ID!,
        "x-pd-environment": "production",
        "x-pd-external-user-id": "{external_user_id}", // any stable ID for this user in your system
        "x-pd-app-slug": "azure_devops",
      },
    },
  },
)

const mcp = new Client({ name: "my-agent", version: "1.0.0" })
await mcp.connect(transport)

const { tools } = await mcp.listTools()

// listTools() hands your model this tool's input schema, so it can
// fill the arguments itself:
const result = await mcp.callTool({
  name: "azure_devops-list-builds",
  arguments: {
    organization: "Organization",
    project: "Project",
  },
})
```

**TypeScript**

```ts
import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "azure_devops-list-builds",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    azure_devops: { authProvisionId: "apn_xxxxxxx" },
    organization: "Organization",
    project: "Project",
  },
})

console.log(result)
```

**cURL**

```bash
curl -X POST https://api.pipedream.com/v1/connect/{project_id}/actions/run \
  -H "Content-Type: application/json" \
  -H "X-PD-Environment: production" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "external_user_id": "{external_user_id}",
    "id": "azure_devops-list-builds",
    "configured_props": {
      "azure_devops": { "authProvisionId": "apn_xxxxxxx" },
      "organization": "Organization",
      "project": "Project"
    }
  }'
```

---

- App: https://pipedream.com/apps/azure-devops.md · All apps: https://pipedream.com/apps