Get Release Bundle v2 Versions in a Specific Environment

Description: Returns a list of all Release Bundle v2 versions whose current location is in a specified environment.

Since: 7.107.1

Security: Requires Read permissions to the target Release Bundle path.

Usage:GET /lifecycle/api/v2/promotion/release-bundles-by-environment/{{environment}}

Path Parameter (mandatory):

Parameter	Type	Description
`environment`	string	The name of the environment to query.

Query Parameters (optional):

Parameter	Type	Description
`repository_key`	string	The Release Bundles repository identifier that identifies where a Release Bundle version resides. If this parameter and the `project` query parameter are not specified, the default value of `release-bundles-v2` is assumed.
`project`	string	The project key used to determine the Release Bundles repository. By convention, each project may contain only one Release Bundles system repository with the name `<project-key>-release-bundles-v2`. This query parameter may be used instead of `repository_key`. Important You must specify either the `repository_key` or the `project` when performing an operation (for example, promotion or distribution) on a Release Bundle v2 that belongs to a specific project.Projects
`offset`	integer	Sets the number of records to skip before returning the query response. Used for pagination purposes. The default value is `0`.
`limit`	integer	Sets the maximum number of versions to return at one time. Used for pagination purposes. The default value is `25`. The maximum value is `255`.
`order_by`	string	Defines the criterion by which to order the list of Release Bundle versions: `created`: Sorts by the Release Bundle version creation timestamp. `created_by`: Sorts by the name of the user who created the Release Bundle version. `release_bundle_name`: Sorts by the Release Bundle name. `release_bundle_version`: Sorts by Release Bundle versions sorted lexicographically. `release_bundle_semver`: Sorts by Release Bundle versions using SemVer rules. (Versions that do not conform to SemVer rules are added to the end sorted lexicographically.) Note The `release_bundle_semver` option pulls the latest 1000 records only and does not support pagination. When this option is selected, the `offset` must be set to 0, and the maximum `limit` is 1000.
`order_asc`	boolean	Defines whether to list the promotions in ascending (`true`) or descending (`false`) order. The default value is `false`.

Response Parameters:

Parameter	Type	Description
`repository_key`	string	The repository that contains the Release Bundle version. The default value is `release-bundles-v2`. If a `project` was specified, the project name is the prefix to the repository name.
`release_bundle_name`	string	The Release Bundle name.
`release_bundle_version`	string	The Release Bundle version.
`release_status`	string	Indicates whether the Release Bundle has been promoted successfully to the official release stage (PROD), making it available for consumption. Possible values are `pre_release` and `released`
`tag`	string	The descriptive tag assigned to the Release Bundle version, if any.
`environment`		The target environment to which the Release Bundle version was promoted.
`created`		The timestamp of the promotion (ISO 8601 standard).
`created_millis`		The timestamp of the promotion in milliseconds.
`created_by`		The name of the user who initiated the promotion operation. Note Names longer than 64 characters will appear truncated.
`project_key`		The project associated with the Release Bundle version, if any.

Status Codes:

Code	Meaning	Description
200	Submitted (asynchronous)	The request was successful.
401	Bad Credentials	The provided authentication is invalid.
403	Permission Denied	The user does not have the necessary permissions to view promotions for this environment.
404	Not Found (repository/build)	The specified environment does not exist or has no promotions.

Examples

The following examples demonstrate how to use to this endpoint to retrieve the Release Bundle versions that match your defined criteria.

Example 1: Get All Release Bundles in a Production Environment

This example contains a basic request to get Release Bundle versions that have been promoted to the PROD environment. The release_status is marked as released.

Request:

curl -u my-user -X GET "http://jfrog-platform-url/lifecycle/api/v2/promotion/release-bundles-by-environment/PROD"

Response:

[
  {
    "repository_key": "my-project-release-bundles-v2",
    "release_bundle_name": "shopping-cart-app",
    "release_bundle_version": "2.5.0",
    "release_status": "released",
    "tag": "stable-2.5.0",
    "environment": "PROD",
    "created": "2025-07-04T10:00:00Z",
    "created_millis": 1751661600000,
    "created_by": "release-manager",
    "project_key": "my-project"
  },
  {
    "repository_key": "my-project-release-bundles-v2",
    "release_bundle_name": "auth-service",
    "release_bundle_version": "1.2.1",
    "release_status": "PROD",
    "tag": "stable-1.2.1",
    "environment": "production",
    "created": "2025-07-03T15:30:00Z",
    "created_millis": 1751585400000,
    "created_by": "release-manager",
    "project_key": "my-project"
  }
]

Example 2: Get Release Bundles in Staging with Sorting and Limits

This request retrieves Release Bundle versions in the Staging environment. Sorting and limits have been defined for pagination purposes. The release_status is marked as pre_release.