Workflows API

Create a workflow

This example creates a transition count workflow that adds the flaky label when a test alarms and removes it when the test recovers:

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}/workflows" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor": {
      "type": "transition_count",
      "window_size": 100,
      "alarm_threshold": 0.1,
      "recover_threshold": 0.05
    },
    "filters": [
      { "key": "scm.branch", "operator": "is", "value": "main" }
    ],
    "alarm_actions": [
      { "type": "add_label", "label": "flaky" }
    ],
    "recover_actions": [
      { "type": "remove_label", "label": "flaky" }
    ]
  }'

{
  "id": "01234567-89ab-4cde-8fab-0123456789ab",
  "url": "https://api.buildkite.com/v2/analytics/organizations/example-org/suites/example-suite/workflows/01234567-89ab-4cde-8fab-0123456789ab",
  "web_url": "https://buildkite.com/organizations/example-org/analytics/suites/example-suite/workflows/01234567-89ab-4cde-8fab-0123456789ab/events",
  "monitor": {
    "type": "transition_count",
    "window_size": 100,
    "alarm_threshold": 0.1,
    "recover_threshold": 0.05
  },
  "filters": [
    { "key": "scm.branch", "operator": "is", "value": "main" }
  ],
  "alarm_actions": [
    { "type": "add_label", "label": "flaky" }
  ],
  "recover_actions": [
    { "type": "remove_label", "label": "flaky" }
  ],
  "created_at": "2026-10-19T01:00:00.000Z",
  "updated_at": "2026-10-19T01:00:00.000Z",
  "created_by": null
}

Required request body properties:

Optional request body properties:

Required scope: write_suites

Success response: 201 Created

List workflows

Returns a paginated list of a suite's workflows, newest first. Each item has the workflow data model fields.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}/workflows"

Required scope: read_suites

Success response: 200 OK

Get a workflow

Returns a single workflow with the workflow data model fields.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}/workflows/{workflow.id}"

Required scope: read_suites

Success response: 200 OK

Update a workflow

Updates the supplied fields and returns the updated workflow. All request body properties are optional. Omitted properties keep their current values, including individual fields within monitor. The monitor's type cannot be changed.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}/workflows/{workflow.id}" \
  -H "Content-Type: application/json" \
  -d '{
    "monitor": {
      "alarm_threshold": 0.2
    },
    "recover_actions": []
  }'

This example changes only the alarm threshold and removes all recovery actions. The remaining monitor settings, filters, and alarm actions stay unchanged.

Each supplied filters, alarm_actions, or recover_actions array replaces that entire list. Send [] to clear a list. Include every entry you want to retain when replacing a list. Use the same monitor, filter, and action fields as for creation. Only fields belonging to the workflow's current monitor type are accepted.

Required scope: write_suites

Success response: 200 OK

Delete a workflow

Deletes the workflow. A subsequent request for the deleted workflow returns 404 Not Found.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/analytics/organizations/{org.slug}/suites/{suite.slug}/workflows/{workflow.id}"

Required scope: write_suites

Success response: 204 No Content

Monitor configuration

The monitor.type selects the monitor and its configuration fields. All fields listed for a type are required on creation. Thresholds must be JSON numbers, not strings. Recovery thresholds must be strictly lower than alarm thresholds.

Filter configuration

Each entry in filters selects execution tags to include in the monitor's input. All three fields are required:

A workflow accepts up to four filters. Keys and values have leading and trailing whitespace removed. Unlike workflows configured in the interface, API-created workflows do not automatically receive a default branch filter. Supply a scm.branch filter explicitly when you want to monitor only your default branch.

Action configuration

Each entry in alarm_actions or recover_actions requires a type and all fields listed for that type. See Alarm and recover actions for action behavior and notification templates.

Each action list accepts up to seven entries. The new_test monitor accepts alarm actions only.

The workflow actions available to you depend on your billing plan.

Workflow data model

Create, get, and update operations return a workflow object. List operations return an array of these objects. The create example shows the response shape.

All fields are present in every workflow response. Send only writable fields in create and update requests. Monitor and action types may be extended, so clients should ignore unknown response fields and handle unknown types.

Error responses

Requests reject unknown fields and incorrect JSON types. Validation failures return 422 Unprocessable Entity, with a JSON Pointer in each error's field identifying the invalid request value:

{
  "message": "Validation Failed",
  "errors": [
    {
      "field": "/monitor/recover_threshold",
      "code": "must be less than alarm threshold"
    }
  ]
}