# Pipeline trigger deliveries API

The pipeline trigger deliveries API provides read-only access to a [pipeline trigger's](/docs/apis/webhooks/incoming/pipeline-triggers) recent deliveries. Use this API to check whether an incoming webhook created a build and, when needed for debugging, inspect the original request that Buildkite Pipelines received.

Buildkite Pipelines retains only a recent history of deliveries for each pipeline trigger. Once a delivery is no longer retained, requests for it return `404 Not Found`.

Use the [pipeline triggers API](/docs/apis/rest-api/pipeline-triggers) to create and manage pipeline triggers.

## Delivery data model



| `id` | UUID of the delivery. |
| --- | --- |
| `url` | Canonical API URL of the delivery. |
| `request_url` | API URL of the delivery's retained request, which includes its parsed payload and headers. See [Get a delivery's request](#get-a-deliverys-request). |
| `received_at` | When the delivery was received. |
| `content_type` | Content type of the incoming request, or `null`. |
| `external_id` | Provider-supplied identifier for the delivery, such as a GitHub delivery ID, or `null`. |
| `status` | Outcome of the delivery. One of: `build_created`: One or more builds were created from this delivery. `not_run`: The delivery didn't qualify to create a build. `failed`: Buildkite Pipelines recorded an error while processing this delivery. `null`: No persisted outcome distinguishes a delivery that is still processing from one that completed without creating a build. |
| `reason` | Reason code for a `not_run` or `failed` status. The value is `null` for a created build or when the recorded reason isn't recognized. See [Delivery reason codes](#delivery-reason-codes). |
| `builds` | Array of builds created from this delivery. Each build contains `id`, `number`, and `url`. The array is empty when no build was created. |



## Delivery reason codes

The `reason` field for a `failed` delivery is one of the following values:

- `invalid_payload`
- `billing_error`
- `build_creation_failed`

The `reason` field for a `not_run` delivery is one of the following values:

- `ci_skip`
- `branch_mismatch`
- `tag_mismatch`
- `pull_requests_disabled`
- `pull_request_branch_mismatch`
- `branches_disabled`
- `tags_disabled`
- `condition_false`
- `condition_failed_parse`
- `preflight_webhook`
- `filter_mismatch`
- `filter_evaluation_failed`

## List a trigger's deliveries

Returns a paginated list of a pipeline trigger's retained deliveries, newest first.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{trigger.id}/deliveries"
```

```json
{
  "items": [
    {
      "id": "f62a1b4d-10f9-4790-bc1c-e2c3a0c80983",
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries/f62a1b4d-10f9-4790-bc1c-e2c3a0c80983",
      "request_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries/f62a1b4d-10f9-4790-bc1c-e2c3a0c80983/request",
      "received_at": "2026-08-11T10:15:32.000Z",
      "content_type": "application/json",
      "external_id": "72d3529e-0135-11e8-9bf8-9df34a9db3a0",
      "status": "build_created",
      "reason": null,
      "builds": [
        {
          "id": "0198f2f4-1c33-4e0a-9d5e-3a4a5b6c7d8e",
          "number": 42,
          "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds/42"
        }
      ]
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries?after=...&per_page=30"
  }
}
```

This endpoint uses cursor-based pagination. The response body is a JSON object with an `items` array and a `links` object. Use the `next` URL from `links` to fetch the next page. Follow that URL instead of constructing cursor values.

Optional [query string parameters](/docs/api#query-string-parameters):



| `per_page` | How many results to return per page. _Default:_ `30` _Maximum:_ `100` |
| --- | --- |
| `after` | Return results after this cursor value. Mutually exclusive with `before`. |
| `before` | Return results before this cursor value. Mutually exclusive with `after`. |



Required scope: `read_pipelines`

Required permission: **Full Access** to the pipeline

Success response: `200 OK`

Error responses:



| `400 Bad Request` | Invalid `per_page` or cursor value, or both `after` and `before` supplied |
| --- | --- |
| `404 Not Found` | No trigger matches the given ID for this pipeline |



## Get a delivery

Returns a single retained delivery.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{trigger.id}/deliveries/{delivery.id}"
```

```json
{
  "id": "f62a1b4d-10f9-4790-bc1c-e2c3a0c80983",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries/f62a1b4d-10f9-4790-bc1c-e2c3a0c80983",
  "request_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f/deliveries/f62a1b4d-10f9-4790-bc1c-e2c3a0c80983/request",
  "received_at": "2026-08-11T10:15:32.000Z",
  "content_type": "application/json",
  "external_id": null,
  "status": "not_run",
  "reason": "branch_mismatch",
  "builds": []
}
```

Required scope: `read_pipelines`

Required permission: **Full Access** to the pipeline

Success response: `200 OK`

Error response: `404 Not Found` when no delivery matches the given ID for this trigger, or the delivery is no longer retained.

## Get a delivery's request

Returns the request that Buildkite Pipelines received for a delivery, including its parsed payload and headers.

Header values are allowlisted before they are returned. Only the GitHub event and delivery ID header values are included. Every other header value is redacted, including authorization, cookie, signature, and token headers. Header names are normalized to lowercase, such as `x-github-event`.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{trigger.id}/deliveries/{delivery.id}/request"
```

```json
{
  "content_type": "application/json",
  "headers": [
    { "name": "authorization", "value": null, "redacted": true },
    { "name": "x-github-delivery", "value": "72d3529e-0135-11e8-9bf8-9df34a9db3a0", "redacted": false },
    { "name": "x-github-event", "value": "pull_request", "redacted": false },
    { "name": "x-hub-signature-256", "value": null, "redacted": true }
  ],
  "payload": {
    "action": "opened",
    "pull_request": {
      "number": 42
    }
  }
}
```

The `headers` value is an empty array when the delivery has no stored headers. The `payload` value isn't redacted and can contain sensitive data from the sending system.

This response is sent with `Cache-Control: private, no-store` and isn't cached.

Required scope: `read_pipelines`

Required permission: **Full Access** to the pipeline

Success response: `200 OK`

Error response: `404 Not Found` when no delivery matches the given ID for this trigger, or the delivery is no longer retained.