---
title: Lists previously created Builds for specified environment.
url: https://developers.wpengine.com/docs/headless-platform/reference/api/endpoints/operations/apps_listbuilds/
image: https://developers.wpengine.com/og/docs/headless-platform/reference/api/endpoints/operations/apps_listbuilds.png
---

# Lists previously created Builds for specified environment.

GET

/v1/accounts/{account}/apps/{app}/environments/{environment}/builds

Select code sample

```sh
curl --request GET \
  --url https://js.wpengineapi.com/v1/accounts/example/apps/example/environments/example/builds \
  --header 'Authorization: Basic <credentials>'
```

-

## Authorizations

- **[basicAuth](https://developers.wpengine.com/docs/headless-platform/reference/api/endpoints/#basicauth)**

## Parameters

### Path Parameters

**account**

required

string

Name of your WP Engine Headless Platform account

**app**

required

string

Name of your Headless Platform application

**environment**

required

string

ID of your environment

### Query Parameters

**pageSize**

integer format: int32

The maximum number of Builds to return. The service may return fewer than this value. If unspecified, no more than 10 builds will be returned. The maximum value is 200; values above 200 will be coerced to 200.

**pageToken**

string

A page token, returned from the previous `ListBuilds` call. Provide this to retrieve the next page.

**orderBy**

string

Default sorting order (empty string) is ascending for `createTime`. The order can be ascending or descending. If we do not specify the order, we will get the result in ascending order. Format: “”, “createTime”, “createTime desc”.

**startTime**

string format: date-time

Only list builds that are newer than `startTime`.

**endTime**

string format: date-time

Only list builds that are older than `endTime`.

## Responses

### 200

A successful response.

Media typeapplication/json

Response including listed Builds.

object

**builds**

A list of Builds.

Array\<object>

Build represents a single build for a given Environment.

Unlike other resources, it is mostly designed to be read by consumers instead of directly being manipulated, hence so many OUTPUT_ONLY annotations. See <https://google.aip.dev/203> for more information about documenting field behavior.

object

**archived**

*Output only. Is the build archived?*

boolean

**branch**

Output only. Name of the branch from which the build was created.

string

**commitMessage**

*commit message*

string

**commitSha**

The exact commit sha being built. At most 40 characters.

string

**createTime**

Output only. Time at which the Build was scheduled.

string format: date-time

**finishTime**

Output only. Time at which execution of the build was finished. Not set if the Build is still running.

string format: date-time

**name**

*Output only. Build name in the format of: \`accounts/{account}/apps/{app}/environments/{environment}/builds/{build}\`*

string

**shellVariables**

*Wrapped list of shell variables for proper json representation*

object

**value**

A list of shell variables available in the App’s container which was used with build.

Array\<object>

*ShellVariable*

Environment variable represents a value available in the environment’s container under the specific key.

object

**key**

*Environment variable key. Must match regex: \`\[-.\_a-zA-Z]\[-.\_a-zA-Z0-9]\*\`. Must not match any of the following case-insensitive globs: WPE\_\*, ATLAS_METADATA\*, HEADLESS_METADATA\_\*, HOME, PORT, K\_\*, TMP, TMPDIR, TEMP*

string

**value**

Environment variable value.

string

**startTime**

Output only. Time at which execution of the build was started.

string format: date-time

**state**

Possible states for a Build.

- STATE_UNSPECIFIED: State of the build is unknown or not applicable.
- PENDING: The Build is pending, no work has yet begun.
- RUNNING: The build is in progress (started and not yet finished).
- SUCCEEDED: The Build finished successfully.

Note: this does not necessarily mean that all BuildTasks comprising this Build succeeded (for example, some tasks may have been optional.)

Note: this does not necessarily mean that this Build is currently deployed. For example, it may have been deployed at some point in the past, and since been superseded by another Build.

- FAILED: The Build has failed.
- CANCELLING: The build is being cancelled
- CANCELLED: The build was cancelled
- QUEUED: The Build is queued.
- TIMEOUT: Build timeout

string

default: STATE_UNSPECIFIED

Allowed values: STATE_UNSPECIFIED PENDING RUNNING SUCCEEDED FAILED CANCELLING CANCELLED QUEUED TIMEOUT

**trigger**

Possible triggers for a Build.

- TRIGGER_UNSPECIFIED: Trigger of the build is unknown or not applicable.
- REBUILD: The Build was triggered by invoking server rebuild method.
- COMMIT: The build was triggered by commit in GitHub.
- WEBHOOK: The build was triggered by webhook system.
- INITIAL: deprecated, use FIRST_BUILD instead
- FIRST_BUILD: The first created build

string

default: TRIGGER_UNSPECIFIED

Allowed values: TRIGGER_UNSPECIFIED REBUILD COMMIT WEBHOOK INITIAL FIRST_BUILD

**nextPageToken**

A token which can be sent as `pageToken` to retrieve the next page. Unset if there are no more pages.

string

**totalSize**

Total number of builds in the entire list of Builds.

integer format: int32

#### Example

```json
{
  "builds": [
    {
      "state": "STATE_UNSPECIFIED",
      "trigger": "TRIGGER_UNSPECIFIED"
    }
  ]
}
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```