:doc:`CloudFormation <../../cloudformation>` / Client / describe_events

***************
describe_events
***************



.. py:method:: CloudFormation.Client.describe_events(**kwargs)

  

  Returns CloudFormation events based on flexible query criteria. Groups events by operation ID, enabling you to focus on individual stack operations during deployment.

   

  An operation is any action performed on a stack, including stack lifecycle actions (Create, Update, Delete, Rollback), change set creation, nested stack creation, and automatic rollbacks triggered by failures. Each operation has a unique identifier (Operation ID) and represents a discrete change attempt on the stack.

   

  Returns different types of events including:

   

  
  * **Progress events** - Status updates during stack operation execution.
   
  * **Validation errors** - Failures from CloudFormation Early Validations.
   
  * **Provisioning errors** - Resource creation and update failures.
   
  * **Hook invocation errors** - Failures from CloudFormation Hook during stack operations.
  

   

  .. note::

    

    One of ``ChangeSetName``, ``OperationId`` or ``StackName`` must be specified as input.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/cloudformation-2010-05-15/DescribeEvents>`_  


  **Request Syntax**
  ::

    response = client.describe_events(
        StackName='string',
        ChangeSetName='string',
        OperationId='string',
        Filters={
            'FailedEvents': True|False
        },
        NextToken='string'
    )
    
  :type StackName: string
  :param StackName: 

    The name or unique stack ID for which you want to retrieve events.

    

  
  :type ChangeSetName: string
  :param ChangeSetName: 

    The name or Amazon Resource Name (ARN) of the change set for which you want to retrieve events.

    

  
  :type OperationId: string
  :param OperationId: 

    The unique identifier of the operation for which you want to retrieve events.

    

  
  :type Filters: dict
  :param Filters: 

    Filters to apply when retrieving events.

    

  
    - **FailedEvents** *(boolean) --* 

      When set to true, only returns failed events within the operation. This helps quickly identify root causes for a failed operation.

      

    
  
  :type NextToken: string
  :param NextToken: 

    The token for the next set of items to return. (You received this token from a previous call.)

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'OperationEvents': [
              {
                  'EventId': 'string',
                  'StackId': 'string',
                  'OperationId': 'string',
                  'OperationType': 'CREATE_STACK'|'UPDATE_STACK'|'DELETE_STACK'|'CONTINUE_ROLLBACK'|'ROLLBACK'|'CREATE_CHANGESET',
                  'OperationStatus': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED',
                  'EventType': 'STACK_EVENT'|'PROGRESS_EVENT'|'VALIDATION_ERROR'|'PROVISIONING_ERROR'|'HOOK_INVOCATION_ERROR',
                  'LogicalResourceId': 'string',
                  'PhysicalResourceId': 'string',
                  'ResourceType': 'string',
                  'Timestamp': datetime(2015, 1, 1),
                  'StartTime': datetime(2015, 1, 1),
                  'EndTime': datetime(2015, 1, 1),
                  'ResourceStatus': 'CREATE_IN_PROGRESS'|'CREATE_FAILED'|'CREATE_COMPLETE'|'DELETE_IN_PROGRESS'|'DELETE_FAILED'|'DELETE_COMPLETE'|'DELETE_SKIPPED'|'UPDATE_IN_PROGRESS'|'UPDATE_FAILED'|'UPDATE_COMPLETE'|'IMPORT_FAILED'|'IMPORT_COMPLETE'|'IMPORT_IN_PROGRESS'|'IMPORT_ROLLBACK_IN_PROGRESS'|'IMPORT_ROLLBACK_FAILED'|'IMPORT_ROLLBACK_COMPLETE'|'EXPORT_FAILED'|'EXPORT_COMPLETE'|'EXPORT_IN_PROGRESS'|'EXPORT_ROLLBACK_IN_PROGRESS'|'EXPORT_ROLLBACK_FAILED'|'EXPORT_ROLLBACK_COMPLETE'|'UPDATE_ROLLBACK_IN_PROGRESS'|'UPDATE_ROLLBACK_COMPLETE'|'UPDATE_ROLLBACK_FAILED'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_COMPLETE'|'ROLLBACK_FAILED',
                  'ResourceStatusReason': 'string',
                  'ResourceProperties': 'string',
                  'ClientRequestToken': 'string',
                  'HookType': 'string',
                  'HookStatus': 'HOOK_IN_PROGRESS'|'HOOK_COMPLETE_SUCCEEDED'|'HOOK_COMPLETE_FAILED'|'HOOK_FAILED',
                  'HookStatusReason': 'string',
                  'HookInvocationPoint': 'PRE_PROVISION',
                  'HookFailureMode': 'FAIL'|'WARN',
                  'DetailedStatus': 'CONFIGURATION_COMPLETE'|'VALIDATION_FAILED',
                  'ValidationFailureMode': 'FAIL'|'WARN',
                  'ValidationName': 'string',
                  'ValidationStatus': 'FAILED'|'SKIPPED',
                  'ValidationStatusReason': 'string',
                  'ValidationPath': 'string'
              },
          ],
          'NextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **OperationEvents** *(list) --* 

        A list of operation events that match the specified criteria.

        
        

        - *(dict) --* 

          Contains detailed information about an event that occurred during a CloudFormation operation.

          
          

          - **EventId** *(string) --* 

            A unique identifier for this event.

            
          

          - **StackId** *(string) --* 

            The unique ID name of the instance of the stack.

            
          

          - **OperationId** *(string) --* 

            The unique identifier of the operation this event belongs to.

            
          

          - **OperationType** *(string) --* 

            The type of operation.

            
          

          - **OperationStatus** *(string) --* 

            The current status of the operation.

            
          

          - **EventType** *(string) --* 

            The type of event.

            
          

          - **LogicalResourceId** *(string) --* 

            The logical name of the resource as specified in the template.

            
          

          - **PhysicalResourceId** *(string) --* 

            The name or unique identifier that corresponds to a physical instance ID of a resource.

            
          

          - **ResourceType** *(string) --* 

            Type of resource.

            
          

          - **Timestamp** *(datetime) --* 

            Time the status was updated.

            
          

          - **StartTime** *(datetime) --* 

            The time when the event started.

            
          

          - **EndTime** *(datetime) --* 

            The time when the event ended.

            
          

          - **ResourceStatus** *(string) --* 

            Current status of the resource.

            
          

          - **ResourceStatusReason** *(string) --* 

            Success or failure message associated with the resource.

            
          

          - **ResourceProperties** *(string) --* 

            The properties used to create the resource.

            
          

          - **ClientRequestToken** *(string) --* 

            A unique identifier for the request that initiated this operation.

            
          

          - **HookType** *(string) --* 

            The type name of the Hook that was invoked.

            
          

          - **HookStatus** *(string) --* 

            The status of the Hook invocation.

            
          

          - **HookStatusReason** *(string) --* 

            Additional information about the Hook status.

            
          

          - **HookInvocationPoint** *(string) --* 

            The point in the operation lifecycle when the Hook was invoked.

            
          

          - **HookFailureMode** *(string) --* 

            Specifies how Hook failures are handled.

            
          

          - **DetailedStatus** *(string) --* 

            Additional status information about the operation.

            
          

          - **ValidationFailureMode** *(string) --* 

            Specifies how validation failures are handled.

            
          

          - **ValidationName** *(string) --* 

            The name of the validation that was performed.

            
          

          - **ValidationStatus** *(string) --* 

            The status of the validation.

            
          

          - **ValidationStatusReason** *(string) --* 

            Additional information about the validation status.

            
          

          - **ValidationPath** *(string) --* 

            The path within the resource where the validation was applied.

            
      
    
      

      - **NextToken** *(string) --* 

        If the request doesn't return all the remaining results, ``NextToken`` is set to a token. To retrieve the next set of results, call ``DescribeEvents`` again and assign that token to the request object's ``NextToken`` parameter. If the request returns all results, ``NextToken`` is set to ``null``.

        
  