Menu
Guides
API Reference

Guides

Monitoring release status with the Release Status Log API

Learn how to query the step-by-step history of your account's releases, read more than 1000 entries, and monitor release status from your own applications.

5 min read

The Release Status Log API returns the history of your account's releases, step by step. Each entry in the log is one step event of a release, such as created, publishing, published, or failed. You choose a time window and get every event that happened in it.

This guide explains how to query the log, follow a single release, read more than 1000 entries, and monitor releases continuously. For the complete list of parameters, response fields, step values, and status codes, see the Get release history endpoint reference.

Before you begin

The user or API key used in the request must have the Visualize Releases License Manager resource.

The token must also have been issued for the same account informed in the an query parameter. A token issued for another account is refused with a 403 status code, even if its user has a role in that account. For an API key, the account is the one the key belongs to.

To learn more, see Authentication overview.

Query the release history

Send a GET request to https://releases.vtex.io/releases/history with the account name and the time window. The following example gets everything that happened in a 24-hour period:


_10
curl --request GET \
_10
--header "Accept: application/json" \
_10
--header "VtexIdclientAutCookie: $TOKEN" \
_10
"https://releases.vtex.io/releases/history?an=myaccount&startDate=2026-10-19T12:00:00Z&endDate=2026-10-20T12:00:00Z"

The time window is [startDate, endDate): startDate is inclusive, and endDate is exclusive. Both must be RFC 3339 date-times. The response returns entries sorted by occurredAt in ascending order:


_25
{
_25
"history": [
_25
{
_25
"id": "6650f1a2c3d4e5f607182930",
_25
"releaseId": "a1b2c3d4",
_25
"accountName": "myaccount",
_25
"step": "created",
_25
"occurredAt": "2026-10-19T14:02:11.000Z",
_25
"actor": {
_25
"type": "user",
_25
"id": "7c1e0f52-0000-0000-0000-000000000000"
_25
}
_25
},
_25
{
_25
"id": "6650f1a2c3d4e5f607182931",
_25
"releaseId": "a1b2c3d4",
_25
"accountName": "myaccount",
_25
"step": "published",
_25
"occurredAt": "2026-10-19T14:05:47.000Z",
_25
"outcome": "success"
_25
}
_25
],
_25
"truncated": false,
_25
"lastOccurredAt": "2026-10-19T14:05:47.000Z"
_25
}

Optional fields, such as outcome, reason, error, actor, and related, are omitted when they have no value.

Limits

LimitValue
Maximum range between startDate and endDate15 days.
Oldest allowed startDate365 days back (history retention window).
Maximum entries per response1000.
Rate limit60 requests per minute per account.
Query timeout5 seconds.

To cover a period longer than 15 days, split it into several windows of up to 15 days each and send one request per window.

Follow a single release

All events of a release share the same releaseId. Group the entries by this field to read the release's sequence. For example:

This is an example of a successful sequence. A step can happen more than once for the same release, and the steps that appear depend on what happened to it.

The log doesn't include release names. To find the name of a release, use the List releases endpoint. The id it returns is the releaseId used in the log.

The following example lists the 20 most recently modified releases that are unscheduled or being published:


_10
curl --request GET \
_10
--header "Accept: application/json" \
_10
--header "VtexIdclientAutCookie: $TOKEN" \
_10
"https://releases.vtex.io/releases?an=myaccount&first=20&status=UNSCHEDULED,PUBLISHING&orderBy=LAST_MODIFIED,DESC"

The response returns the releases in the releases array. Find the entry whose id matches the releaseId of the log and read its name:


_14
{
_14
"releases": [
_14
{
_14
"id": "a1b2c3d4",
_14
"name": "Black Friday banners",
_14
"status": "PUBLISHING"
_14
}
_14
],
_14
"pagination": {
_14
"endCursor": "WyIxNzI5MjY0MDAwMDAwIiwiYTFiMmMzZDQiXQ==",
_14
"hasNextPage": false,
_14
"totalCount": 1
_14
}
_14
}

You can also filter by name. The endpoint returns up to 30 releases per page. When hasNextPage is true, send the request again with after set to the endCursor value. For the complete list of parameters and response fields, see the List releases endpoint reference.

Read more than 1000 entries

A response holds at most 1000 entries. When truncated is true, more entries exist in your time window. To read them:

  1. Send the request again with startDate set to the lastOccurredAt value of the previous response, and the same endDate.
  2. Repeat step 1 until truncated is false.
  3. De-duplicate the entries by id. Several entries can share the same timestamp at the boundary between two responses, so the same entry may be returned twice.

Monitor releases continuously

To monitor release status from your own application, poll the endpoint at regular intervals:

  1. Store the lastOccurredAt value of the last entry you processed.
  2. In the next request, use that value as startDate, and use the current date and time as endDate.
  3. De-duplicate entries by id before processing them.

This avoids reading old entries again and keeps your integration within the rate limit.

A date in the future is accepted as endDate.

Handle errors

Status codeWhat to do
400Check the request. This status is returned for missing or invalid dates, a startDate that isn't before endDate, a range over 15 days, a startDate older than the retention window, an unknown account, or a missing authorization token.
401The token is invalid. Generate a new token.
403Check if the user or API key has the Visualize Releases resource, and if the token was issued for the account informed in an.
429Wait the number of seconds informed in the Retry-After response header, then retry. Don't retry immediately. Requests refused with 403 don't count toward the rate limit.
503The query took too long. Retry with a narrower time window.

Narrower time windows return faster. If you receive a 503 status code, shorten the window between startDate and endDate.