list_runs_in_organization
Retrieve and filter run history across all workspaces in a Terraform Cloud organization for auditing, monitoring deployments, and tracking specific runs by commit or author.
Instructions
List runs across all workspaces in an organization
Retrieves run history across all workspaces in an organization with powerful filtering. Useful for organization-wide auditing, monitoring deployments across teams, or finding specific runs by commit or author.
API endpoint: GET /organizations/{organization}/runs
Args: organization: The organization name page_number: Page number to fetch (default: 1) page_size: Number of results per page (default: 20) filter_operation: Filter by operation type filter_status: Filter by status filter_source: Filter by source filter_status_group: Filter by status group filter_timeframe: Filter by timeframe filter_agent_pool_names: Filter by agent pool names filter_workspace_names: Filter by workspace names search_user: Search by VCS username search_commit: Search by commit SHA search_basic: Basic search across run attributes
Returns: List of runs across workspaces with metadata and pagination details
See: docs/tools/run.md for reference documentation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| organization | Yes | ||
| page_number | No | ||
| page_size | No | ||
| filter_operation | No | ||
| filter_status | No | ||
| filter_source | No | ||
| filter_status_group | No | ||
| filter_timeframe | No | ||
| filter_agent_pool_names | No | ||
| filter_workspace_names | No | ||
| search_user | No | ||
| search_commit | No | ||
| search_basic | No |
Implementation Reference
- The main execution handler for the 'list_runs_in_organization' tool. It validates inputs using the Pydantic model, builds query parameters, and performs the API request to list runs across all workspaces in the specified organization.
async def list_runs_in_organization( organization: str, page_number: int = 1, page_size: int = 20, filter_operation: Optional[str] = None, filter_status: Optional[str] = None, filter_source: Optional[str] = None, filter_status_group: Optional[str] = None, filter_timeframe: Optional[str] = None, filter_agent_pool_names: Optional[str] = None, filter_workspace_names: Optional[str] = None, search_user: Optional[str] = None, search_commit: Optional[str] = None, search_basic: Optional[str] = None, ) -> APIResponse: """List runs across all workspaces in an organization Retrieves run history across all workspaces in an organization with powerful filtering. Useful for organization-wide auditing, monitoring deployments across teams, or finding specific runs by commit or author. API endpoint: GET /organizations/{organization}/runs Args: organization: The organization name page_number: Page number to fetch (default: 1) page_size: Number of results per page (default: 20) filter_operation: Filter by operation type filter_status: Filter by status filter_source: Filter by source filter_status_group: Filter by status group filter_timeframe: Filter by timeframe filter_agent_pool_names: Filter by agent pool names filter_workspace_names: Filter by workspace names search_user: Search by VCS username search_commit: Search by commit SHA search_basic: Basic search across run attributes Returns: List of runs across workspaces with metadata and pagination details See: docs/tools/run.md for reference documentation """ # Create request using Pydantic model for validation request = RunListInOrganizationRequest( organization=organization, page_number=page_number, page_size=page_size, filter_operation=filter_operation, filter_status=filter_status, filter_source=filter_source, filter_status_group=filter_status_group, filter_timeframe=filter_timeframe, filter_agent_pool_names=filter_agent_pool_names, filter_workspace_names=filter_workspace_names, search_user=search_user, search_commit=search_commit, search_basic=search_basic, ) # Use the unified query params utility function params = query_params(request) # Make API request return await api_request( f"organizations/{organization}/runs", method="GET", params=params ) - Pydantic model (RunListInOrganizationRequest) that defines and validates all input parameters for the list_runs_in_organization tool, including organization name, pagination, and various filtering options.
class RunListInOrganizationRequest(APIRequest): """Request parameters for listing runs in an organization. These parameters map to the query parameters in the runs API. The endpoint returns a paginated list of runs across all workspaces in an organization, with options for filtering by workspace name, status, and other criteria. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#list-runs-in-an-organization See: docs/models/run.md for reference """ organization: str = Field( ..., description="The organization name", min_length=3, pattern=r"^[a-z0-9][-a-z0-9_]*[a-z0-9]$", ) 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" ) filter_operation: Optional[str] = Field( None, description="Filter runs by operation type, comma-separated", max_length=100, ) filter_status: Optional[str] = Field( None, description="Filter runs by status, comma-separated", max_length=100 ) filter_source: Optional[str] = Field( None, description="Filter runs by source, comma-separated", max_length=100 ) filter_status_group: Optional[str] = Field( None, description="Filter runs by status group", max_length=50 ) filter_timeframe: Optional[str] = Field( None, description="Filter runs by timeframe", max_length=50 ) filter_agent_pool_names: Optional[str] = Field( None, description="Filter runs by agent pool names, comma-separated", max_length=100, ) filter_workspace_names: Optional[str] = Field( None, description="Filter runs by workspace names, comma-separated", max_length=250, ) search_user: Optional[str] = Field( None, description="Search for runs by VCS username", max_length=100 ) search_commit: Optional[str] = Field( None, description="Search for runs by commit SHA", max_length=40 ) search_basic: Optional[str] = Field( None, description="Basic search across run ID, message, commit SHA, and username", max_length=100, ) - terraform_cloud_mcp/server.py:66-66 (registration)The MCP tool registration decorator that exposes the list_runs_in_organization handler as an MCP tool.
mcp.tool()(runs.list_runs_in_organization)