1. Docs
  2. Reference
  3. REST API Docs
  4. Stack Updates

Stack Updates

    Stack Updates are operations that create, update, or delete resources in a Pulumi stack. The Stack Updates API allows you to list updates, check status, and view detailed events for each operation.

    Get Engine Events

    ▼
    GET /api/stacks/{orgName}/{projectName}/{stackName}/destroy/{updateID}/events

    Returns the engine events for the specified update. Engine events represent individual resource operations and diagnostic messages produced during the update. Supports pagination via continuation tokens and filtering by engine event type codes or resource URN. The include_non_activated parameter controls whether events not yet marked as activated are included.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • updateID string path required
      The update ID
    • continuationToken string query optional
      Continuation token for paginated results
    • include_non_activated boolean query optional
      When true, includes events that have not yet been activated; when false or omitted, only activated events are returned
    • type array query optional
      Filter results to only include events matching these engine event type codes
    • urn string query optional
      Filter results to only include events for the specified resource URN

    Responses

    200 OK
    Schema: GetUpdateEventsResponse
    • events array[EngineEvent] required
      Events are returned sorted by their internal sequence number (not exposed to the API). So the last Event in the slice is the most recent event which was stored in the database. (Should sort identical to timestamp, but may not if we support parallel writes.)
    • ↳ timestamp integer required
      Timestamp of the event (seconds).
    • ↳ type string required
      Type describes which payload object is associated with the event, such that in JavaScript event[event.type] is never undefined/null.
    • ↳ cancelEvent AppCancelEvent optional
      Present when type is cancelEvent.
    • ↳ stdoutEvent AppStdoutEngineEvent optional
      Present when type is stdoutEvent.
    • ↳ diagnosticEvent AppDiagnosticEvent optional
      Present when type is diagnosticEvent.
    • ↳ preludeEvent AppPreludeEvent optional
      Present when type is preludeEvent.
    • ↳ summaryEvent AppSummaryEvent optional
      Present when type is summaryEvent.
    • ↳ resourcePreEvent AppResourcePreEvent optional
      Present when type is resourcePreEvent.
    • ↳ resOutputsEvent AppResOutputsEvent optional
      Present when type is resOutputsEvent.
    • ↳ resOpFailedEvent AppResOpFailedEvent optional
      Present when type is resOpFailedEvent.
    • ↳ policyEvent AppPolicyEvent optional
      Present when type is policyEvent.
    • ↳ policyRemediationEvent AppPolicyRemediationEvent optional
      Present when type is policyRemediationEvent.
    • ↳ policyLoadEvent AppPolicyLoadEvent optional
      Present when type is policyLoadEvent.
    • ↳ policyAnalyzeSummaryEvent AppPolicyAnalyzeSummaryEvent optional
      Present when type is policyAnalyzeSummaryEvent.
    • ↳ policyRemediateSummaryEvent AppPolicyRemediateSummaryEvent optional
      Present when type is policyRemediateSummaryEvent.
    • ↳ policyAnalyzeStackSummaryEvent AppPolicyAnalyzeStackSummaryEvent optional
      Present when type is policyAnalyzeStackSummaryEvent.
    • ↳ startDebuggingEvent AppStartDebuggingEvent optional
      Present when type is startDebuggingEvent.
    • ↳ progressEvent AppProgressEvent optional
      Present when type is progressEvent.
    • ↳ errorEvent AppErrorEvent optional
      Present when type is errorEvent.
    • continuationToken string required
      ContinuationToken is an opaque value the client can send to fetch more recent events if the update is still in progress. Will be nil once all events have been returned and the update is complete.
    Errors: 400 Invalid continuation token.

    Get Update Status For Update

    ▼
    GET /api/stacks/{orgName}/{projectName}/{stackName}/update/{updateID}

    Returns the current status and results of a standard (pulumi up) update, including whether it is still in progress, succeeded, or failed. Supports pagination of results via the continuationToken query parameter.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • updateID string path required
      The update ID
    • continuationToken string query optional
      Continuation token for paginated results

    Responses

    200 OK
    Schema: AppUpdateResults
    • status enum required
      The current status
      Values: not started, requested, running, failed, succeeded, cancelled
    • events array[AppUpdateEvent] required
      List of events
    • ↳ index string required
      The index
    • ↳ kind enum required
      The kind
      Values: stdout, stderr
    • ↳ fields map[string]object required
      The fields
    • continuationToken string optional

      ContinuationToken is an opaque value used to indiciate the end of the returned update results. Pass it in the next request to obtain subsequent update events.

      The same continuation token may be returned if no new update events are available, but the update is still in-progress.

      A value of nil means that no new updates will be available. Everything has been returned to the client and the update has completed.

    Errors: 400 invalid query parameter

    Get Stack Updates

    ▼
    GET /api/stacks/{orgName}/{projectName}/{stackName}/updates

    Returns the update history for a stack. Each update includes its kind (update, preview, refresh, destroy, import), start and end times, result status, resource changes summary, and resource count. Supports pagination via ‘page’ and ‘pageSize’ query parameters (page 0 returns all results, pageSize=1 with page=1 returns only the most recent update). The ‘output-type’ parameter controls the response format: when unset, returns a legacy format; when set, returns a paginated response.

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • output-type string query optional
      Controls the response format; when unset returns the legacy format, otherwise returns the paginated format
    • page integer query optional
      Page number for paginated results (0-indexed, where 0 returns all results)
    • pageSize integer query optional
      Number of results per page (must be >= 1 when page > 0)

    Responses

    200 OK
    Errors: 400 Invalid 'page' value. or Invalid 'pageSize' value.

    Get Latest Stack Previews

    ▼
    GET /api/stacks/{orgName}/{projectName}/{stackName}/updates/latest/previews

    Returns all preview operations associated with the latest stack update version. Previews are dry-run operations that show what changes would be made. Supports pagination via page and pageSize parameters (page 0 returns all results). The asc parameter controls sort order (ascending or descending by chronological order).

    Request Parameters

    • orgName string path required
      The organization name
    • projectName string path required
      The project name
    • stackName string path required
      The stack name
    • asc boolean query optional
      When true, sorts results in ascending chronological order; when false or omitted, sorts in descending order
    • page integer query optional
      Page number for paginated results (0-indexed, where 0 returns all results)
    • pageSize integer query optional
      Number of results per page (must be >= 1 when page > 0)

    Responses

    200 OK
    Schema: GetStackUpdatesResponse
    • updates array[UpdateInfo] required
      The list of stack updates
    • ↳ info AppUpdateInfo required
      The underlying update information from the Pulumi CLI.
    • ↳ updateID string required
      UpdateID is the underlying Update’s ID on the PPC.
    • ↳ githubCommitInfo GitHubCommitInfo optional

      If the update’s metadata indicates the update environment was from a GitHub based repo we try to lookup the commit that was HEAD at the time of the update.

      May not be set depending on which API is used to obtain the UpdateInfo object.

    • ↳ version integer required
      Version of the stack that this UpdateInfo describe.
    • ↳ latestVersion integer required
      LatestVersion of the stack in general. i.e. the latest when Version == LatestVersion.
    • ↳ requestedBy UserInfo required
      The user who requested the update.
    • ↳ policyPacks array[AppPolicyPackMetadata] optional
      The Policy Packs that were required for this update.
    • ↳ requestedByToken string optional
      The access token used to request the update, if applicable.
    • itemsPerPage integer required
      The number of items per page
    • total integer required
      The total number of updates
    Errors: 400 Invalid 'page' value. Must be >= 0. or Invalid 'pageSize' value. Must be >= 1. or Invalid 'pageSize' value. Must be 0 or unset when 'page' is 0.