Tests

List tests

List tests in a Buildkite Test Engine suite with execution metrics aggregated over a selected time window. Supports filtering, metric sorting, and pagination.

get/organizations/{org}/suites/{suite_slug}/tests

Request

  • Base URL: https://api.buildkite.com/v2/analytics
  • URL: https://api.buildkite.com/v2/analytics/organizations/{org}/suites/{suite_slug}/tests
  • Auth: HTTP bearer

Path parameters

orgstring required

Organization slug

suite_slugstring required

Suite slug.

Query parameters

labelsstring

Filter by comma-separated test labels. Prefix a label with ! to exclude it, for example flaky,!slow.

pageinteger

Page number for pagination (minimum 1).

per_pageinteger

Results per page for pagination (minimum 1, maximum 100).

periodstring
Example:7days

Relative aggregation window, such as 7days or 28days. Whether selected by period or timestamps, the aggregation window cannot exceed the organization's maximum Test Engine window. Cannot be combined with min_timestamp or max_timestamp.

max_timestampstring date-time

End of the aggregation window in RFC 3339 format. Defaults to the current time when omitted. Cannot be combined with period.

min_timestampstring date-time

Start of the aggregation window in RFC 3339 format. When omitted, defaults to the organization's default Test Engine period before the current time. Cannot be combined with period.

min_executionsinteger

Return only tests with at least this many executions after applying the selected time window and execution filters.

branchstring

Filter executions included in the metrics by branch. Prefix with ! to exclude an exact branch or suffix with * to match by prefix, for example !main or feature*. Use at most one operator.

ownersstring

Filter by comma-separated test owner slugs. Prefix an owner with ! to exclude it, for example payments,!platform.

sort_by'duration_avg' | 'duration_sum' | 'duration_min' | 'duration_max' | 'reliability'

Metric used to sort results: duration_avg, duration_sum, duration_min, duration_max, or reliability. Defaults to duration_avg. Metrics cover only executions in the selected window.

order'asc' | 'desc'

Sort direction: asc or desc. Defaults to desc.

state'enabled' | 'muted' | 'skipped'

Test state.

Filter by test state: enabled, muted, or skipped.

tagsstring

Filter by comma-separated execution tags in key:value form. Values support ! for exclusion and * for prefix matching. Result values additionally support ~ for any matching execution and ^ for every execution matching, for example framework:!rspec,scm.branch:feature*,result:^passed.

Headers

Buildkite-Versionstring required
Example:2026-08-01

Opt in to the versioned Test Engine API response.

Response

A list of tests with metrics.

idstring uuid
urlstring uri
web_urlstring uri
scopestring
namestring
locationstring
file_namestring
state'enabled' | 'muted' | 'skipped'

Test state.

state_changed_atstring date-time nullable

When the test entered its current state. Null for enabled tests, which are the default and carry no state record.

labelsstring[]
reliabilitynumber nullable

Ratio of passed executions to passed and failed executions. Null when there were no executions in the aggregation window.

duration_avgnumber nullable

Average execution duration in seconds. Null when there were no executions in the aggregation window.

duration_sumnumber nullable

Total execution duration in seconds. Null when there were no executions in the aggregation window.

duration_minnumber nullable

Shortest execution duration in seconds. Null when there were no executions in the aggregation window.

duration_maxnumber nullable

Longest execution duration in seconds. Null when there were no executions in the aggregation window.

executions_countinteger

Number of executions in the aggregation window.

Changes

No recorded changes to this operation across all 1 revision of this API.