generate_audience
Description: Generates a lookalike audience from an ICP persona. Takes personas from analyze_customers output and executes the targeting expression for the selected persona and strategy. Optionally applies geographic filtering.
Note: The cluster identifiers in persona expressions are cluster_hash values (stable identifiers) from analyze_customers output, not numeric cluster IDs. These hash values persist across data rebuilds, ensuring reliable targeting.
Tool Identifier: generate_audience
Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| csv_key | string | Yes | - | Min length: 1 | S3 key from generate_url_for_upload (for workflow tracking) |
| personas | array | Yes | - | Min 1 item | Personas array from analyze_customers.icp_synthesis.personas |
| market_context | object | Yes | - | See analyze_customers | Market context for agentic decision-making |
| persona_index | number | Yes | - | Min: 0 | Index of the persona to use (0-based) |
| strategy | string | Yes | - | "precision", "balanced", or "reach" | Targeting strategy |
| geo_filter | object | No | - | See below | Geographic filter with radius |
| custom_expression | string | No | - | Boolean expression | Override persona expression |
| audience_limit | number | No | 1000000 | Min: 1, Max: 15000000 | Maximum audience size |
| identifier_types | array | No | ["email"] | Valid: email, phone, address, name, maid | Identifier types to include in export |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
geo_filter Object:
| Field | Type | Required | Description |
|---|---|---|---|
| latitude | number | Yes | Latitude (-90 to 90) |
| longitude | number | Yes | Longitude (-180 to 180) |
| radius_miles | number | Yes | Radius in miles |
Targeting Strategies:
| Strategy | Description | Use When |
|---|---|---|
| precision | AND-heavy expressions, narrow targeting | Need high-quality, precise matches |
| balanced | Mixed AND/OR operators | General audience building |
| reach | OR-heavy expressions, broad targeting | Need maximum audience size |
Request Schema:
interface GenerateAudienceParams {
csv_key: string;
personas: Array<{
name: string;
description: string;
key_traits: Array<{...}>;
expressions: {
precision: string;
balanced: string;
reach: string;
};
}>;
market_context: {
base_context: string;
refinements?: string[];
};
persona_index: number;
strategy: "precision" | "balanced" | "reach";
geo_filter?: {
latitude: number;
longitude: number;
radius_miles: number;
};
custom_expression?: string;
audience_limit?: number;
identifier_types?: ("email" | "phone" | "address" | "name" | "maid")[];
workflow_id?: string;
}Output Format
Success Response:
{
expression: string; // The boolean expression used
audience_size: number; // Total audience size
audience_download_url: string; // Presigned URL (expires in 1 hour)
expires_at: string; // ISO timestamp when URL expires
identifier_types: string[]; // Identifier types in export
geo_filter_applied?: { // Only if geo_filter was provided
latitude: number;
longitude: number;
radius_miles: number;
};
warning?: { // Only if audience size suboptimal
code: string;
message: string;
suggestion: string;
};
tool_trace_id: string;
workflow_id: string;
}Warning Codes:
| Code | Trigger | Message |
|---|---|---|
| AUDIENCE_TOO_SMALL | Size < 10,000 | Audience size is below optimal threshold (10,000) |
| AUDIENCE_TOO_LARGE | Size > 10,000,000 | Audience size exceeds optimal threshold (10,000,000) |
Example Response:
{
"expression": "a8f3bc1d2e3f4a5b6c7d8e9f0a1b2c3d AND b2e4df5a6b7c8d9e0f1a2b3c4d5e6f7a",
"audience_size": 1250000,
"audience_download_url": "https://watt-exports.s3.amazonaws.com/audiences/...",
"expires_at": "2025-01-16T15:30:00Z",
"identifier_types": ["email"],
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Example Response (With Warning):
{
"expression": "a8f3bc1d2e3f4a5b6c7d8e9f0a1b2c3d AND b2e4df5a6b7c8d9e0f1a2b3c4d5e6f7a AND c3f5de8a9b0c1d2e3f4a5b6c7d8e9f0a",
"audience_size": 5000,
"audience_download_url": "https://watt-exports.s3.amazonaws.com/audiences/...",
"expires_at": "2025-01-16T15:30:00Z",
"identifier_types": ["email"],
"warning": {
"code": "AUDIENCE_TOO_SMALL",
"message": "Audience size of 5,000 is below optimal threshold (10,000).",
"suggestion": "Consider using 'reach' strategy for broader targeting."
},
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Error Handling
Common Errors:
- Invalid persona_index: "persona_index 5 is out of bounds. Available personas: 0-2"
- Missing personas: "At least one persona is required"
- Invalid strategy: "strategy must be one of: precision, balanced, reach"
- Export failed: "Failed to generate audience export. Check that the expression is valid."
Usage Examples
Example 1: Basic audience generation
{
"csv_key": "uploads/abc123/customers.csv",
"personas": [...],
"market_context": {
"base_context": "B2B SaaS platform",
"refinements": []
},
"persona_index": 0,
"strategy": "balanced"
}Example 2: With geographic filter
{
"csv_key": "uploads/abc123/customers.csv",
"personas": [...],
"market_context": {
"base_context": "B2B SaaS platform",
"refinements": []
},
"persona_index": 0,
"strategy": "precision",
"geo_filter": {
"latitude": 37.7749,
"longitude": -122.4194,
"radius_miles": 50
}
}Example 3: With custom expression
{
"csv_key": "uploads/abc123/customers.csv",
"personas": [...],
"market_context": {
"base_context": "B2B SaaS platform",
"refinements": []
},
"persona_index": 0,
"strategy": "balanced",
"custom_expression": "a8f3bc1d2e3f4a5b6c7d8e9f0a1b2c3d OR b2e4df5a6b7c8d9e0f1a2b3c4d5e6f7a OR c3f5de8a9b0c1d2e3f4a5b6c7d8e9f0a"
}Example 4: With multiple identifier types
{
"csv_key": "uploads/abc123/customers.csv",
"personas": [...],
"market_context": {
"base_context": "B2B SaaS platform",
"refinements": []
},
"persona_index": 0,
"strategy": "reach",
"identifier_types": ["email", "phone"]
}