list_state_versions
Retrieve and filter state versions in a Terraform Cloud workspace. Lists paginated results with metadata, enabling efficient tracking and management of infrastructure configurations.
Instructions
List state versions in a workspace.
Retrieves a paginated list of all state versions in a Terraform Cloud workspace. Results can be filtered using status to find specific state versions.
API endpoint: GET /state-versions
Args: organization: The name of the organization that owns the workspace workspace_name: The name of the workspace to list state versions from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) filter_status: Filter state versions by status: 'pending', 'finalized', or 'discarded'
Returns: Paginated list of state versions with their configuration settings and metadata
See: docs/tools/state_versions.md for reference documentation
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter_status | No | ||
| organization | Yes | ||
| page_number | No | ||
| page_size | No | ||
| workspace_name | Yes |
Implementation Reference
- The core handler function for the 'list_state_versions' tool. It validates input parameters using Pydantic models, constructs query parameters, and performs an API request to list state versions from a Terraform Cloud workspace.@handle_api_errors async def list_state_versions( organization: str, workspace_name: str, page_number: int = 1, page_size: int = 20, filter_status: Optional[str] = None, ) -> APIResponse: """List state versions in a workspace. Retrieves a paginated list of all state versions in a Terraform Cloud workspace. Results can be filtered using status to find specific state versions. API endpoint: GET /state-versions Args: organization: The name of the organization that owns the workspace workspace_name: The name of the workspace to list state versions from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) filter_status: Filter state versions by status: 'pending', 'finalized', or 'discarded' Returns: Paginated list of state versions with their configuration settings and metadata See: docs/tools/state_versions.md for reference documentation """ # Convert filter_status string to enum if provided status_enum = None if filter_status: try: status_enum = StateVersionStatus(filter_status) except ValueError: valid_values = ", ".join([s.value for s in StateVersionStatus]) raise ValueError( f"Invalid filter_status value: {filter_status}. Valid values: {valid_values}" ) # Validate parameters params = StateVersionListRequest( filter_workspace_name=workspace_name, filter_organization_name=organization, page_number=page_number, page_size=page_size, filter_status=status_enum, ) # Build query parameters using utility function query = query_params(params) # Make API request return await api_request("state-versions", params=query)
- terraform_cloud_mcp/server.py:113-113 (registration)Registers the list_state_versions function as an MCP tool in the server.py main file.mcp.tool()(state_versions.list_state_versions)
- Pydantic model used for input validation and query parameter construction in the list_state_versions handler.Defines the parameters for the state version listing API including pagination and filtering options. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions#list-state-versions See: docs/models/state_versions.md for reference """ filter_workspace_name: Optional[str] = Field( None, description="Filter by workspace name", ) filter_organization_name: Optional[str] = Field( None, description="Filter by organization name", ) filter_status: Optional[StateVersionStatus] = Field( None, description="Filter state versions by status", ) page_number: Optional[int] = Field( 1, ge=1, description="Page number to fetch", ) page_size: Optional[int] = Field( 20, ge=1, le=100, description="Number of results per page", )