App Environment History API

The App Environment History API allows you to retrieve the deployment history and activity timeline for an app environment in Quave Cloud. This is useful for understanding when deployments occurred, tracking changes over time, and finding deployment times for log filtering.

Make sure to read the Get Started document to understand how the API works.

Note: This API endpoint accepts only user tokens (not environment tokens).

Get App Environment History

To retrieve deployment history for an app environment, send a GET request to the /api/public/v1/app-env/history endpoint. You need to provide either appEnvId or envName to identify the environment.

Required Parameters (Either/Or)

You must provide either appEnvId or envName:

Parameter	Type	Description
appEnvId	String	The ID of the app environment to retrieve history for.
envName	String	The CLI environment name (alternative to appEnvId).

Optional Parameters

Parameter	Type	Description
limit	Number	Number of activities to return. Default: 50. Maximum: 200.
offset	Number	Number of activities to skip (for pagination). Default: 0.
fromDate	String	Start timestamp for filtering (ISO 8601 format, e.g., "2024-01-15T10:00:00.000Z").
toDate	String	End timestamp for filtering (ISO 8601 format, e.g., "2024-01-15T11:00:00.000Z").

Response Structure

The response is a JSON object with the following fields:

Field	Type	Description
appEnvId	String	The app environment ID.
activities	Array	Array of activity entries (see below).
pagination	Object	Pagination information (see below).

Activity Entry

Each activity in the activities array contains:

Field	Type	Description
contentId	String	Content version ID (null for non-deployment activities).
version	Number	Version number (null if not a deployment).
status	String	Activity status (e.g., DEPLOYED, SCALED, STOPPED).
timestamp	Date	When this activity occurred.
userId	String	User who triggered the activity (null for automated activities).
gitCommitId	String	Git commit SHA (null for CLI deployments or non-build activities).
gitBranch	String	Git branch name (null for CLI deployments or non-build activities).
resources	Object	Resource allocation at the time of this activity.
duration	Number	Duration in milliseconds from start to completion (null if unavailable).

Resources Object

The resources object within each activity shows the resource allocation at that time:

Field	Type	Description
cpu	Number	CPU allocation in cores (null if not set).
memory	Number	Memory allocation in MB (null if not set).
zClouds	Number	zClouds allocation (null if not set).

Pagination Object

The pagination object provides pagination information:

Field	Type	Description
total	Number	Total number of activities available.
limit	Number	Number of activities returned in this response.
offset	Number	Number of activities skipped.
hasMore	Boolean	Whether there are more activities available.

Example: Get Recent History (with appEnvId)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/history?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&limit=10'

Example: Get History (with envName)

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/history?envName=production&limit=10'

Example: Get History with Date Range

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/history?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&fromDate=2024-01-01T00:00:00.000Z&toDate=2024-01-31T23:59:59.999Z'

Example Response

{
  "appEnvId": "5f7b1b7b7b7b7b7b7b7b7b7b",
  "activities": [
    {
      "contentId": "abc123def456",
      "version": 42,
      "status": "DEPLOYED",
      "timestamp": "2024-01-15T10:30:00.000Z",
      "userId": "user123",
      "gitCommitId": "a1b2c3d4e5f6",
      "gitBranch": "main",
      "resources": {
        "cpu": 1.0,
        "memory": 512,
        "zClouds": 2
      },
      "duration": 45000
    },
    {
      "contentId": "def456ghi789",
      "version": 41,
      "status": "DEPLOYED",
      "timestamp": "2024-01-14T15:20:00.000Z",
      "userId": "user123",
      "gitCommitId": "g7h8i9j0k1l2",
      "gitBranch": "main",
      "resources": {
        "cpu": 1.0,
        "memory": 512,
        "zClouds": 2
      },
      "duration": 52000
    },
    {
      "contentId": null,
      "version": null,
      "status": "SCALED",
      "timestamp": "2024-01-13T09:00:00.000Z",
      "userId": "user456",
      "gitCommitId": null,
      "gitBranch": null,
      "resources": {
        "cpu": 1.0,
        "memory": 512,
        "zClouds": 2
      },
      "duration": null
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Example: Pagination

To retrieve the next page of results:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/history?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&limit=10&offset=10'

Use Cases

This endpoint is useful for:

1. Deployment Tracking - See when deployments occurred and who triggered them
2. Audit Trail - Track all changes to the environment over time
3. Log Filtering - Get the last deployment time to filter logs ("show logs since last deploy")
4. Performance Analysis - Track deployment durations and identify slow deploys
5. Resource History - See how resource allocation has changed over time
6. Troubleshooting - Identify when issues started by correlating with deployments

Activity Status Values

Common status values include:

• DEPLOYED - Successful deployment completed
• SCALED - Resource scaling completed
• STOPPED - Environment was stopped
• RUNNING - Environment started/resumed
• PENDING - Initial state
• UPDATING - Update in progress

Understanding Duration

The duration field shows the time from start to completion:

• For deployments: time from build start to successful deployment
• May be null if timing information is unavailable
• Measured in milliseconds (divide by 1000 for seconds)
• Longer durations may indicate:
  • Large Docker images
  • Complex build processes
  • Slow health checks
  • Resource constraints

Finding Last Deployment Time

To get just the most recent deployment:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/history?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&limit=1'

The first activity's timestamp is the last deployment time, which you can use to filter logs:

# Get last deployment time
LAST_DEPLOY=$(curl ... | jq -r '.activities[0].timestamp')

# Get logs since last deployment
curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    "https://api.quave.cloud/api/public/v1/logs?appEnvId=5f7b1b7b7b7b7b7b7b7b7b7b&from=${LAST_DEPLOY}"

Error Responses

• 400 - Missing required parameters or invalid date format
• 401 - User not authenticated
• 403 - User doesn't have permission to access this app environment
• 404 - App environment not found for the given appEnvId or envName

Notes

Environment Identification:

• You can use either appEnvId or envName to identify the environment
• If both are provided, appEnvId takes precedence

Date Filtering:

• Dates must be in ISO 8601 format (e.g., "2024-01-15T10:00:00.000Z")
• Both fromDate and toDate are inclusive
• You can provide just fromDate or just toDate

Pagination:

• Default limit is 50, maximum is 200
• Activities are returned in reverse chronological order (newest first)
• Use offset to skip activities for pagination
• Check pagination.hasMore to determine if there are more results

Activity Types:

• Most activities are deployments with contentId and version
• Scaling operations may not have contentId (scale-only changes)
• Git information is only available for GitHub-based deployments