audiences_list
Retrieve configured audience lists from Piwik PRO Customer Data Platform to analyze and manage customer segments for targeted analytics and marketing.
Instructions
List audiences from Piwik PRO CDP.
Retrieves a list of audiences that are configured in the Piwik PRO
Customer Data Platform for the specified app.
Args:
app_id: UUID of the app to list audiences for
Returns:
Dictionary containing audience list including:
- audiences: List of audience objects with id, name, description, etc.
- total: Total number of audiences available
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes |
Implementation Reference
- Core implementation of the audiences_list tool logic. Fetches audiences from Piwik PRO CDP API, maps to AudienceSummary models, and returns formatted AudienceListMCPResponse.
def list_audiences(app_id: str) -> AudienceListMCPResponse: """ List audiences from Piwik PRO CDP. Retrieves a list of audiences that are configured in the Piwik PRO Customer Data Platform for the specified app. Args: app_id: UUID of the app to list audiences for Returns: Dictionary containing audience list and metadata Raises: RuntimeError: If authentication fails or API request fails """ try: client = create_piwik_client() response = client.cdp.list_audiences(app_id=app_id) # Extract relevant information and convert to AudienceSummary models audiences_data = [] for audience in response or []: audience_summary = AudienceSummary( id=audience.get("id", ""), name=audience.get("name", ""), description=audience.get("description", ""), membership_duration_days=audience.get("membership_duration_days", 30), version=audience.get("version", 1), created_at=audience.get("created_at"), updated_at=audience.get("updated_at"), is_author=audience.get("is_author", False), ) audiences_data.append(audience_summary) return AudienceListMCPResponse( audiences=audiences_data, total=len(audiences_data), ) except (BadRequestError, NotFoundError) as e: raise RuntimeError(f"Failed to list audiences: {e}") except Exception as e: raise RuntimeError(f"Unexpected error listing audiences: {e}") - Thin MCP handler function registered as the 'audiences_list' tool, delegates to core implementation in audiences.list_audiences.
@mcp.tool("audiences_list") def audiences_list(app_id: str) -> AudienceListMCPResponse: """List audiences from Piwik PRO CDP. Retrieves a list of audiences that are configured in the Piwik PRO Customer Data Platform for the specified app. Args: app_id: UUID of the app to list audiences for Returns: Dictionary containing audience list including: - audiences: List of audience objects with id, name, description, etc. - total: Total number of audiences available """ return _list_audiences(app_id=app_id) - src/piwik_pro_mcp/tools/__init__.py:32-32 (registration)Call to register_cdp_tools which registers the audiences_list tool among CDP tools.
register_cdp_tools(mcp) - Pydantic model defining the output schema of the audiences_list tool response.
class AudienceListMCPResponse(BaseModel): """MCP-specific audience list response that matches documented schema.""" audiences: List[AudienceSummary] = Field(..., description="List of audiences") total: int = Field(..., description="Total number of audiences available") - Pydantic model for individual audience summary used in the list response.
class AudienceSummary(BaseModel): """Audience summary for list responses that matches MCP tool documentation.""" id: str = Field(..., description="Audience UUID") name: str = Field(..., description="Audience name") description: str = Field(..., description="Audience description") membership_duration_days: int = Field(..., description="Membership duration in days") version: int = Field(..., description="Audience version") created_at: Optional[datetime] = Field(None, description="Creation timestamp") updated_at: Optional[datetime] = Field(None, description="Last update timestamp") is_author: bool = Field(..., description="Whether current user is the author")