# Build tests API

## List tests for a build

Returns a [paginated list](/docs/rest-api#pagination) of tests that ran in a Buildkite Pipelines build. Each test includes execution metrics aggregated over the build's time window. The response includes tests from every Buildkite Test Engine suite associated with the build that the API token can access.

The build identifier must be the build UUID, not the pipeline build number.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/builds/{build.id}/tests"
```

```json
[
  {
    "id": "a915535c-a8f1-4e1a-bd6a-a5589e09f349",
    "url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_name/tests/a915535c-a8f1-4e1a-bd6a-a5589e09f349",
    "web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_name/tests/a915535c-a8f1-4e1a-bd6a-a5589e09f349",
    "scope": "User#email",
    "name": "is correctly formatted",
    "location": "./spec/models/user_spec.rb:42",
    "file_name": "./spec/models/user_spec.rb",
    "labels": ["flaky"],
    "reliability": 0.98,
    "duration_avg": 0.213,
    "duration_sum": 23.856,
    "duration_min": 0.108,
    "duration_max": 1.942,
    "executions_count": 113,
    "executions_count_by_result": {
      "passed": 110,
      "failed": 2,
      "skipped": 1
    }
  }
]
```

The aggregation window starts when the build is created, unless the organization's maximum Test Engine time window requires a later start. It ends when the build finishes. For a running build, the window ends at the current time. The window cannot extend beyond 24 hours after the build was created.



| `reliability` | The reliability of the test, calculated from its passed and failed executions and expressed as a decimal fraction. This is `null` when the test has no passed or failed executions in the build. |
| --- | --- |
| `duration_avg` | The average execution duration, in seconds. |
| `duration_sum` | The total execution duration, in seconds. |
| `duration_min` | The shortest execution duration, in seconds. |
| `duration_max` | The longest execution duration, in seconds. |
| `executions_count` | The number of executions in the build. |
| `executions_count_by_result` | The number of executions in the build, broken down by result. The `passed` and `failed` counts are always present. The `skipped`, `pending`, and `unknown` counts are only present when they're non-zero. |



### Query string parameters

Some [query string parameters](/docs/api#query-string-parameters) support one or more of the additional operators listed below.



| `!` | Excludes the specified value. |
| --- | --- |
| `*` | Matches values that start with the specified value. |
| `~` | Returns groups that contain at least one matching execution. This operator is only available for the `result` tag. |
| `^` | Returns groups where every execution matches. This operator is only available for the `result` tag. |



Optional query string parameters:



| `labels` | Filters the results by a comma-separated list of test labels. _Example:_ `?labels=flaky,!slow` _Supported operators:_ `!` |
| --- | --- |
| `branch` | Only aggregates executions from branches that match the specified value. Use at most one operator. _Example:_ `?branch=feature*` _Supported operators:_ `! *` |
| `owners` | Filters the results by a comma-separated list of test owner slugs. _Example:_ `?owners=payments,!platform` _Supported operators:_ `!` |
| `state` | Filters the results by test state. Valid values are `enabled`, `muted`, and `skipped`. _Example:_ `?state=muted` |
| `tags` | Filters the results by a comma-separated list of execution tags, using `key:value` syntax. A `build.id` filter cannot override the build UUID in the request path. _Example:_ `?tags=framework:!rspec,scm.branch:feature*,result:^passed` _Supported operators:_ `! *`. The `result` tag also supports `^ ~`. |
| `sort_by` | The metric to sort the results by. Valid values are `duration_avg`, `duration_sum`, `duration_min`, `duration_max`, and `reliability`. The default value is `duration_avg`. _Example:_ `?sort_by=reliability` |
| `order` | The direction to sort the results in. Valid values are `asc` and `desc`. The default value is `desc`. _Example:_ `?order=asc` |



This endpoint is [paginated](/docs/apis/rest-api#pagination).

Required scope: `read_suites`

Success response: `200 OK`