# Cloud Tool Results API . projects . histories

## Instance Methods

Returns the executions Resource.

Creates a History.

Gets a History.

Lists Histories for a given Project.

Retrieves the next page of results.

### Method Details

`create(projectId, body, requestId=None)`

    Creates a History.

    The returned History will have the id set.

    May return any of the following canonical error codes:

    - PERMISSION_DENIED - if the user is not authorized to write to project - INVALID_ARGUMENT - if the request is malformed - NOT_FOUND - if the containing project does not exist

    Args:
      projectId: string, A Project id.

    Required. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # A History represents a sorted list of Executions ordered by the start_timestamp_millis field (descending). It can be used to group all the Executions of a continuous build.
          #
          # Note that the ordering only operates on one-dimension. If a repository has multiple branches, it means that multiple histories will need to be used in order to order Executions per branch.
        "displayName": "A String", # A short human-readable (plain text) name to display in the UI. Maximum of 100 characters.
            #
            # - In response: present if set during create. - In create request: optional
        "name": "A String", # A name to uniquely identify a history within a project. Maximum of 100 characters.
            #
            # - In response always set - In create request: always set
        "historyId": "A String", # A unique identifier within a project for this History.
            #
            # Returns INVALID_ARGUMENT if this field is set or overwritten by the caller.
            #
            # - In response always set - In create request: never set
      }

      requestId: string, A unique request ID for server to detect duplicated requests. For example, a UUID.

    Optional, but strongly recommended.

    Returns:
      An object of the form:

        { # A History represents a sorted list of Executions ordered by the start_timestamp_millis field (descending). It can be used to group all the Executions of a continuous build.
            #
            # Note that the ordering only operates on one-dimension. If a repository has multiple branches, it means that multiple histories will need to be used in order to order Executions per branch.
          "displayName": "A String", # A short human-readable (plain text) name to display in the UI. Maximum of 100 characters.
              #
              # - In response: present if set during create. - In create request: optional
          "name": "A String", # A name to uniquely identify a history within a project. Maximum of 100 characters.
              #
              # - In response always set - In create request: always set
          "historyId": "A String", # A unique identifier within a project for this History.
              #
              # Returns INVALID_ARGUMENT if this field is set or overwritten by the caller.
              #
              # - In response always set - In create request: never set
        }

`get(projectId, historyId)`

    Gets a History.

    May return any of the following canonical error codes:

    - PERMISSION_DENIED - if the user is not authorized to read project - INVALID_ARGUMENT - if the request is malformed - NOT_FOUND - if the History does not exist

    Args:
      projectId: string, A Project id.

    Required. (required)
      historyId: string, A History id.

    Required. (required)

    Returns:
      An object of the form:

        { # A History represents a sorted list of Executions ordered by the start_timestamp_millis field (descending). It can be used to group all the Executions of a continuous build.
            #
            # Note that the ordering only operates on one-dimension. If a repository has multiple branches, it means that multiple histories will need to be used in order to order Executions per branch.
          "displayName": "A String", # A short human-readable (plain text) name to display in the UI. Maximum of 100 characters.
              #
              # - In response: present if set during create. - In create request: optional
          "name": "A String", # A name to uniquely identify a history within a project. Maximum of 100 characters.
              #
              # - In response always set - In create request: always set
          "historyId": "A String", # A unique identifier within a project for this History.
              #
              # Returns INVALID_ARGUMENT if this field is set or overwritten by the caller.
              #
              # - In response always set - In create request: never set
        }

`list(projectId, pageToken=None, pageSize=None, filterByName=None)`

    Lists Histories for a given Project.

    The histories are sorted by modification time in descending order. The history_id key will be used to order the history with the same modification time.

    May return any of the following canonical error codes:

    - PERMISSION_DENIED - if the user is not authorized to read project - INVALID_ARGUMENT - if the request is malformed - NOT_FOUND - if the History does not exist

    Args:
      projectId: string, A Project id.

    Required. (required)
      pageToken: string, A continuation token to resume the query at the next item.

    Optional.
      pageSize: integer, The maximum number of Histories to fetch.

    Default value: 20. The server will use this default if the field is not set or has a value of 0. Any value greater than 100 will be treated as 100.

    Optional.
      filterByName: string, If set, only return histories with the given name.

    Optional.

    Returns:
      An object of the form:

        { # Response message for HistoryService.List
        "nextPageToken": "A String", # A continuation token to resume the query at the next item.
            #
            # Will only be set if there are more histories to fetch.
            #
            # Tokens are valid for up to one hour from the time of the first list request. For instance, if you make a list request at 1PM and use the token from this first request 10 minutes later, the token from this second response will only be valid for 50 minutes.
        "histories": [ # Histories.
          { # A History represents a sorted list of Executions ordered by the start_timestamp_millis field (descending). It can be used to group all the Executions of a continuous build.
                #
                # Note that the ordering only operates on one-dimension. If a repository has multiple branches, it means that multiple histories will need to be used in order to order Executions per branch.
              "displayName": "A String", # A short human-readable (plain text) name to display in the UI. Maximum of 100 characters.
                  #
                  # - In response: present if set during create. - In create request: optional
              "name": "A String", # A name to uniquely identify a history within a project. Maximum of 100 characters.
                  #
                  # - In response always set - In create request: always set
              "historyId": "A String", # A unique identifier within a project for this History.
                  #
                  # Returns INVALID_ARGUMENT if this field is set or overwritten by the caller.
                  #
                  # - In response always set - In create request: never set
            },
        ],
      }

`list_next(previous_request, previous_response)`

    Retrieves the next page of results.

    Args:
      previous_request: The request for the previous page. (required)
      previous_response: The response from the request for the previous page. (required)

    Returns:
      A request object that you can call 'execute()' on to request the next
      page. Returns None if there are no more items in the collection.