# How to Get Version History for an App Using IPATool

> Discover how to get app version history with IPATool. Learn to use the list versions command to retrieve all historical app version IDs from the App Store.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: how-to-guide
- Published: 2026-08-31

---

**IPATool's `list-versions` command queries the App Store to retrieve every historical version ID available for a specific iOS application.**

To get version history for an app using IPATool, you authenticate with your Apple ID and execute the command against either a numeric App ID or a bundle identifier. The tool implements a multi-step resolution flow that handles automatic re-authentication, App Store lookup, and XML parsing to return a complete list of external version identifiers.

## Understanding the `list-versions` Architecture

The implementation spans two primary source files in the `majd/ipatool` repository. The command logic resides in [`cmd/list_versions.go`](https://github.com/majd/ipatool/blob/main/cmd/list_versions.go), while the low-level App Store communication lives in [`pkg/appstore/appstore_list_versions.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go).

### Account Acquisition and Authentication

When you invoke `ipatool list-versions`, the `ListVersionsCmd` struct first validates your session by calling `AppStore.AccountInfo`. If your stored password token has expired, the system automatically re-authenticates via `AppStore.Login` before proceeding with the version query. This ensures the subsequent request to Apple's servers includes valid credentials without manual intervention.

### App Resolution from Bundle Identifiers

You can specify the target app using either `--app-id` (the numerical App Store ID) or `--bundle-identifier` (the reverse-domain string). If you provide only a bundle identifier, the command executes `AppStore.Lookup` to resolve the corresponding numerical `app-id` before requesting version data.

### The Private App Store Request

Once authentication and resolution are complete, `appstore.ListVersions` constructs a **POST** request mimicking the official iOS App Store client. The `listVersionsRequest` payload includes three critical components: the device’s MAC address (used as a GUID), your account’s DS-ID, and the target application’s ID. This request targets Apple’s internal endpoints to access historical version data not exposed through public APIs.

### Parsing the XML Response

The App Store returns an XML document that [`pkg/appstore/appstore_list_versions.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go) parses into the `ListVersionsOutput` struct. The parser specifically extracts two fields:

- **`softwareVersionExternalIdentifiers`** – An array containing every historic version ID available for the application
- **`softwareVersionExternalIdentifier`** – The single newest version ID

The CLI then logs the array under the key `externalVersionIdentifiers` and renders the output in your selected format.

## Retrieving Version History via CLI

Before running version queries, ensure you have an active authenticated session:

```bash
ipatool auth login

```

### Query by App ID

Use the numerical App Store ID to retrieve version history directly:

```bash
ipatool list-versions --app-id 123456789

```

### Query by Bundle Identifier

If you know the bundle identifier but not the App ID, IPATool resolves it automatically:

```bash
ipatool list-versions --bundle-identifier com.example.myapp

```

### Machine-Readable JSON Output

For scripting and automation, specify the JSON format to receive structured data:

```bash
ipatool list-versions -b com.example.myapp --format json

```

The JSON response contains the full history array and the latest version identifier:

```json
{
  "externalVersionIdentifiers": [
    "20000123",
    "20000234",
    "20000345"
  ],
  "latestExternalVersionID": "20000345"
}

```

## Programmatic Access with Go

You can integrate version history retrieval directly into Go applications using the `pkg/appstore` package. The `AppStore` interface defined in [`pkg/appstore/appstore.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore.go) exposes the `ListVersions` method for programmatic use:

```go
import (
    "github.com/majd/ipatool/v2/pkg/appstore"
)

func getHistory(appID int64, acc appstore.Account) ([]string, error) {
    out, err := appstoreClient.ListVersions(appstore.ListVersionsInput{
        Account: acc,
        App:     appstore.App{ID: appID},
    })
    if err != nil {
        return nil, err
    }
    return out.ExternalVersionIdentifiers, nil
}

```

This approach allows you to handle the `ListVersionsInput` struct directly, manage the `Account` object programmatically, and process the `ExternalVersionIdentifiers` slice without shelling out to the CLI.

## Summary

- **`list-versions`** is the primary command for retrieving historical App Store versions according to the `majd/ipatool` source code.
- The command automatically handles expired authentication by calling `AppStore.Login` when `AccountInfo` detects invalid tokens.
- You can target apps by either `--app-id` or `--bundle-identifier`, with the latter automatically resolving to the former via `AppStore.Lookup`.
- [`pkg/appstore/appstore_list_versions.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go) sends a POST request containing your DS-ID and a device GUID, then parses the XML response to extract `softwareVersionExternalIdentifiers`.
- Output formats include human-readable `text` and machine-readable `json`, both exposing the `externalVersionIdentifiers` array.

## Frequently Asked Questions

### Can I retrieve version history without knowing the App ID?

Yes. If you only know the bundle identifier (e.g., `com.company.appname`), use the `--bundle-identifier` flag. The `ListVersionsCmd` implementation in [`cmd/list_versions.go`](https://github.com/majd/ipatool/blob/main/cmd/list_versions.go) automatically calls `AppStore.Lookup` to resolve the numerical App ID before fetching the version history.

### What authentication is required to use `list-versions`?

You must have a valid Apple ID session established via `ipatool auth login`. The command checks `AppStore.AccountInfo` before executing, and if your password token has expired, it automatically triggers `AppStore.Login` to refresh credentials without requiring you to re-run the login command manually.

### What information does the version history response contain?

The response contains the `externalVersionIdentifiers` array, which lists every historical version ID available for the app on the App Store, and `latestExternalVersionID`, which identifies the current release. These values map to the `softwareVersionExternalIdentifiers` and `softwareVersionExternalIdentifier` fields in Apple's internal XML response, as parsed in [`pkg/appstore/appstore_list_versions.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_list_versions.go).

### Can I use IPATool's version history feature in my own Go application?

Yes. Import `github.com/majd/ipatool/v2/pkg/appstore` and call the `ListVersions` method with a `ListVersionsInput` struct containing your `Account` and target `App` details. The method returns a `ListVersionsOutput` struct containing the `ExternalVersionIdentifiers` slice for programmatic processing.