Growth Agent Segments API

Creates audience segments and performs ICP analysis using Growth Marketer agents to identify profitable audiences and enhance targeting precision.

Endpoints

Create Audience Segments


POST /api/agents/growth/segments

Creates new audience segments for a website using Growth Marketer agent analysis.

Enhance Segments with ICP Analysis


POST /api/agents/growth/segments/icp

Performs detailed ICP (Ideal Customer Profile) analysis on existing segments to enhance targeting precision.

Request Body

Create Segments Request

Parameter	Type	Required	Description
`siteId`	string	Yes	ID of the website to analyze for segments
`agent_id`	string	No	ID of the agent to handle segment analysis
`userId`	string	No	ID of the user creating the segments
`segmentData`	object	No	Object containing segment analysis configuration

segmentData Object

Parameter	Type	Required	Description
`segmentCount`	number	No	Number of segments to create (default: 5)

Example Request


{
  "siteId": "site_456",
  "agent_id": "agent_growth_123",
  "userId": "user_789",
  "segmentData": {
    "segmentCount": 5
  }
}

ICP Analysis Request

Parameter	Type	Required	Description
`siteId`	string	Yes	ID of the website containing the segments
`agent_id`	string	No	ID of the agent to handle ICP analysis
`userId`	string	No	ID of the user requesting analysis
`segmentIds`	array	Yes	Array of segment IDs to analyze

Example Request


{
  "siteId": "site_456",
  "agent_id": "agent_growth_123",
  "userId": "user_789",
  "segmentIds": ["seg_123", "seg_456", "seg_789"]
}

Try It

You can test this API directly using our API Tester interface. The API tester allows you to create audience segments and perform ICP analysis.

Create Segments Mode:

Site ID: The ID of the website to analyze for segments

ICP Analysis Mode:

Site ID: The ID of the website containing the segments
Segment IDs: Array of segment IDs to analyze

Optional fields for both modes:

Agent ID: ID of the agent to handle analysis
User ID: ID of the user creating/analyzing segments

API Tester

Este componente te permite probar diferentes endpoints de API.

Generated Command Structure

The system generates a command object with the following structure to control the segment analysis process:


{
  "task": "analyze audience segments",
  "userId": "user_789",
  "agentId": "agent_growth_123",
  "site_id": "site_456",
  "description": "Analyze website and identify the most profitable audience segments",
  "targets": [
    {
      "segments": [
        {
          "name": "Digital Content Creators",
          "description": "Professionals aged 20-40 dedicated to creating digital content",
          "targetAudience": "media_entertainment",
          "estimatedSize": "189,000",
          "estimatedValue": "9,000,000",
          "profitabilityScore": 0.88
        }
      ]
    }
  ],
  "context": "Segment Analysis Context:\n{\n  \"segmentCount\": 5\n}",
  "supervisor": [
    {
      "agent_role": "data_analyst",
      "status": "not_initialized"
    },
    {
      "agent_role": "marketing_strategist",
      "status": "not_initialized"
    }
  ]
}

Response

Create Segments Success Response


{
  "success": true,
  "data": {
    "command_id": "cmd_abc123",
    "site_id": "site_456",
    "url": null,
    "segmentsAnalyzed": 5,
    "segmentsCreated": 3,
    "segments": [
      {
        "id": "seg_content_creators",
        "name": "Digital Content Creators",
        "description": "Professionals aged 20-40 dedicated to creating digital content",
        "summary": "Highly profitable segment of digital creators",
        "estimatedSize": "189,000",
        "estimatedValue": "9,000,000",
        "profitabilityScore": 0.88,
        "confidenceScore": 0.85,
        "targetAudience": "media_entertainment",
        "language": "en",
        "attributes": {
          "demographic": {
            "ageRange": "20-40",
            "gender": "mixed",
            "income": "medium-high"
          }
        },
        "audienceProfile": {
          "adPlatforms": {
            "googleAds": {
              "demographics": {
                "ageRanges": ["25-34", "35-44"]
              }
            }
          }
        },
        "createdInDatabase": true,
        "created_at": "2023-06-15T14:30:00Z"
      }
    ],
    "saved_to_database": true
  }
}

ICP Analysis Success Response


{
  "success": true,
  "data": {
    "command_id": "cmd_icp456",
    "site_id": "site_456",
    "segmentsAnalyzed": 3,
    "segmentsUpdated": 3,
    "segments": [
      {
        "id": "seg_content_creators",
        "name": "Digital Content Creators",
        "description": "Professionals aged 20-40 dedicated to creating digital content",
        "icpEnhanced": true,
        "icpEnhancementData": {
          "demographic_insights": {
            "age_distribution": "25-35 (60%), 36-45 (30%), 20-24 (10%)",
            "income_analysis": "$50K-$100K annually with variable income",
            "education_background": "Bachelor's degree in creative fields",
            "geographic_distribution": "Urban areas, creative hubs"
          },
          "psychographic_profile": {
            "values_and_beliefs": "Creativity, authenticity, innovation",
            "lifestyle_preferences": "Work-life balance, flexible schedules",
            "personality_traits": "Creative, ambitious, tech-savvy",
            "motivations": "Self-expression, audience growth, monetization"
          },
          "behavioral_insights": {
            "buying_behavior": "Research-heavy, value-conscious, trend-followers",
            "media_consumption": "Video content, social media, podcasts",
            "technology_adoption": "Early adopters, mobile-first",
            "engagement_preferences": "Visual content, interactive formats"
          }
        },
        "updated_at": "2023-06-15T15:30:00Z"
      }
    ],
    "saved_to_database": true
  }
}

Error Response


{
  "success": false,
  "error": {
    "code": "SEGMENTS_NOT_FOUND",
    "message": "No segments found for the provided IDs and site"
  }
}

Error Codes

Code	Description
`INVALID_REQUEST`	The request parameters are invalid
`INVALID_JSON`	Could not parse request body as JSON
`SITE_NOT_FOUND`	The specified site does not exist
`USER_NOT_FOUND`	The specified user does not exist
`GROWTH_MARKETER_NOT_FOUND`	No Growth Marketer agent found for this site
`SEGMENTS_NOT_FOUND`	No segments found for the provided IDs and site
`SEGMENTS_VERIFICATION_FAILED`	Failed to verify segments existence
`SEGMENT_ANALYSIS_FAILED`	Growth Marketer segment analysis failed
`ICP_ANALYSIS_FAILED`	Growth Marketer ICP analysis failed
`NO_SEGMENTS_CREATED`	No segments could be created from analysis results
`NO_SEGMENTS_UPDATED`	No segments could be updated with ICP results
`INTERNAL_SERVER_ERROR`	An error occurred while processing the request

Segment Database Structure

Field	Type	Required	Description
`id`	uuid	Yes	Unique identifier for the segment
`name`	text	Yes	Name of the audience segment
`description`	text	No	Detailed description of the segment
`summary`	text	No	Brief summary of the segment
`estimated_size`	text	No	Estimated audience size
`estimated_value`	text	No	Estimated monetary value
`profitability_score`	decimal	No	Profitability score (0-1)
`confidence_score`	decimal	No	Analysis confidence score (0-1)
`target_audience`	text	No	Target audience category
`language`	text	No	Primary language of the segment
`attributes`	jsonb	No	Segment attributes (demographic, behavioral, etc.)
`audience_profile`	jsonb	No	Detailed audience profile for ad platforms
`site_id`	uuid	Yes	ID of the website (foreign key to sites.id)
`user_id`	uuid	No	ID of the user (foreign key to users.id)
`created_at`	timestamptz	Auto	Creation timestamp (default: now())
`updated_at`	timestamptz	Auto	Last update timestamp (default: now())

Target Audiences

Category	Description
`enterprise`	Large enterprise customers
`smb`	Small and medium businesses
`e_commerce`	E-commerce and retail focused
`tech`	Technology sector audiences
`finance`	Financial services sector
`healthcare`	Healthcare and medical sector
`education`	Educational institutions
`media_entertainment`	Media and entertainment industry
`professional`	Professional services

Notes

The command executes asynchronously using advanced AI models
Automatically analyzes website content to identify profitable audience segments
Segments include detailed targeting information for advertising platforms
All segments are saved to the database with profitability scores
The system integrates with existing marketing automation platforms