# List Builds

> List App Builds using the Applivery API. Covers both the Integrations and Workspace APIs for querying Build history and status.

Source: https://docs.applivery.com/en/app-distribution/api/builds/list-builds/  •  Last updated: 2026-03-31

**Key topics:** Integrations API, Workspace API, API Authentication, Query Parameters, Build Status, Applivery, API, App API Token, Service Account, iOS, Android

---

**TL;DR:** Learn how to list app builds using Applivery's Integrations or Workspace API with appropriate authentication and query parameters.

Returns a paginated list of Builds for a given App. This is useful for querying build history, checking processing status after an upload, or building dashboards and automation scripts that act on specific Builds.

Applivery provides two separate APIs for listing Builds, each requiring a different authentication credential.

---

## Choosing the right API

| | Integrations API | Workspace API |
|---|---|---|
| **Designed for** | Per-app integrations, CI/CD pipelines, build tools | Workspace-level automation across multiple Apps |
| **Authentication** | App API Token (per-app) | Service Account token (Workspace-level) |
| **Base URL** | `https://api.applivery.io` | `https://api.applivery.io` |
| **App context** | Implicit — token is already scoped to an App | Explicit — `organizationId` and `applicationId` required in the path |
| **Typical users** | Scripts checking build status, post-upload polling | Platform engineers querying Builds across multiple Apps |

:::warning
Access to the different APIs might not be available in your current plan. Please check availability on our [pricing page](https://www.applivery.com/app-distribution-pricing/).
:::

---

## Integrations API

Use this endpoint when querying Builds within the scope of a single app. Authentication uses an **App API Token**, which is scoped to the specific App.

To create an App API Token, see [Apps API Authentication](https://docs.applivery.com/en/app-distribution/api/app-api-token/).

### Endpoint

```
GET https://api.applivery.io/v1/integrations/builds
```

### Authentication

```
Authorization: Bearer <your_app_token>
```

### Query Parameters

All parameters are optional. When no filters are applied, the endpoint returns all Builds for the App associated with the token, ordered by creation date descending.

| Parameter | Type | Description |
|---|---|---|
| `versionName` | String | Filter by human-readable version name. E.g., `RC-1`, `v2.4.0-beta`. |
| `status` | String | Filter by build processing status. Allowed values: `pending`, `in_progress`, `processed`, `error`. |
| `os` | String | Filter by operating system. Allowed values: `ios`, `android`. |
| `page` | Integer | Page number for pagination. Starts at `1`. |
| `limit` | Integer | Maximum number of Builds to return per page. |

### Example Request

```bash
curl 'https://api.applivery.io/v1/integrations/builds?status=processed&os=ios&page=1&limit=20' \
  -X GET \
  -H 'Authorization: Bearer YOUR_APP_TOKEN'
```

### Responses

**✓ 200 OK**

```json
{
  "status": true,
  "data": {
    "items": [
      {
        "id": "string",
        "status": "processed",
        "tags": ["string"],
        "versionName": "string",
        "application": "string",
        "applicationInfo": {
          "id": "string",
          "name": "string",
          "slug": "string",
          "picture": "string"
        },
        "changelog": "string",
        "info": {
          "icon": "string",
          "android": {
            "targetSdkVersion": "string",
            "minSDKVersion": "string",
            "packageName": "string",
            "platformBuildVersionName": "string",
            "platformBuildVersionCode": "string",
            "versionName": "string",
            "versionCode": "string",
            "icon": "string"
          },
          "ios": {
            "plist": {
              "CFBundleDisplayName": "string",
              "CFBundleSupportedPlatforms": ["string"],
              "MinimumOSVersion": "string",
              "CFBundleIdentifier": "string",
              "CFBundleShortVersionString": "string",
              "CFBundleVersion": "string",
              "CFBundleName": "string",
              "CFBundleIcons": ["string"],
              "UIDeviceFamily": ["string"]
            },
            "mobileprovision": {
              "ExpirationDate": "2019-08-24T14:15:22Z",
              "TeamIdentifier": "string",
              "ProvisionsAllDevices": true,
              "TeamName": "string",
              "ProvisionedDevices": "string",
              "signingType": "ad-hoc"
            }
          },
          "pkg": {
            "CFBundleDisplayName": "string",
            "CFBundleIdentifier": "string",
            "CFBundleShortVersionString": "string",
            "CFBundleVersion": "string",
            "CFBundleName": "string"
          }
        },
        "size": 0,
        "processTime": 0,
        "queuedTime": 0,
        "versionCode": "string",
        "error": "string",
        "errorCode": "string",
        "os": "ios",
        "deployer": {
          "name": "string",
          "info": {
            "commitMessage": "string",
            "commit": "string",
            "branch": "string",
            "triggerTimestamp": "string",
            "buildUrl": "string",
            "ciUrl": "string",
            "repositoryUrl": "string",
            "buildNumber": "string",
            "tag": "string"
          }
        },
        "uploadedBy": {
          "id": "string",
          "email": "user@example.com",
          "firstName": "string",
          "lastName": "string",
          "picture": "string"
        },
        "originalExtension": "string",
        "storageProvider": {
          "id": "string",
          "name": "string",
          "region": "string"
        },
        "hasEmmJson": true,
        "updatedAt": "2019-08-24T14:15:22Z",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ]
  }
}
```

**✗ 401 Unauthorized**

```json
{
  "status": false,
  "error": {
    "code": 4002,
    "message": "No auth token"
  }
}
```

**✗ 404 Not Found**

```json
{
  "status": false,
  "error": {
    "code": 3001,
    "message": "Entity not found"
  }
}
```

:::tip
Use `status=pending` or `status=in_progress` to poll for Builds that are still being processed after an upload. Once `status` returns `processed`, the Build is ready. If `status` is `error`, check the `error` and `errorCode` fields for details, and refer to [Build Processing Codes](https://docs.applivery.com/en/app-distribution/builds/processing-error-codes/) for resolution steps.
:::

---

## Workspace API

Use this endpoint when querying Builds at the Workspace level — for example, in platform engineering workflows where a single credential needs to list Builds across multiple Apps.

Authentication uses a **Service Account** token, which is Workspace-scoped and not tied to any individual app. The App context is provided explicitly via path parameters.

To create a Service Account, see [Service Accounts](https://docs.applivery.com/en/platform/api/service-accounts/).

### Endpoint

```
GET https://api.applivery.io/v1/organizations/{organizationId}/apps/{applicationId}/builds
```

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `organizationId` | String | Yes | The unique identifier of your Applivery organization. |
| `applicationId` | String | Yes | The unique identifier of the App whose Builds you want to list. |

### Authentication

```
Authorization: Bearer <your_service_account_token>
```

### Query Parameters

The Workspace API accepts the same query parameters as the Integrations API. 

### Example Request

```bash
curl 'https://api.applivery.io/v1/organizations/ORG_ID/apps/APP_ID/builds?status=processed&os=android&page=1&limit=10' \
  -X GET \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN'
```