---
title: "Controller Handle Train Segmentation Audience"
method: POST
path: "/audience/segmentation/build"
tags: ["audience"]
---

# Controller Handle Train Segmentation Audience

`POST /audience/segmentation/build`

Build a segmentation model for an audience

## Request body

- TrainSegPayload
  - `seg_id` string, required — The ID of the segmentation model to train
  - `audience_id` string, required — The ID of the audience to train the segmentation model on
  - `options` TrainSegOptions, required
    - `k` union — The number of segments to create (allowed: 3, 4, 5, or 'dynamic')
      - 3 | 4 | 5
      - 'dynamic'
    - `household` boolean — Whether to train at the household level

## Response `201`

Successful Response

- AudienceSegmentationRecord
  - `id` integer, nullable — ID of this object.
  - `created_at` string, date-time, nullable — datetime object representing when this object was created.
  - `updated_at` string, date-time, nullable — datetime object representing when this object was updated.
  - `deleted_at` string, date-time, nullable — datetime object representing when this object was deleted.
  - `seg_id` string, required — The ID of the lookalike audience.
  - `audience_id_fs` string, required — The ID of the audience.
  - `status` 'PRESTART' | 'FINDING_FEATURES' | 'COLLECTING_IDS' | 'STAGING_DATA' | 'COMPLETED' | 'FAILED' | 'FITTING_SUPERVISED_MODEL' | 'BACKTESTING_SUPERVISED_MODEL' | 'CLUSTERING_RESULTS' | 'TRAINING_STACK' | 'PREDICTING_SUPERVISED_MODEL' | 'PREDICTING_STACK_MODEL' | 'RESCALING_RESULTS' | 'WRITING' | 'LOGGING_PROBABILITIES' | 'LOGGING_INFERENCE_SET_SIZE' | 'FINDING_OPTIMAL_K' | 'FINDING_CENTERS' | 'FINDING_SEGMENT_DIFFS' | 'FINDING_SEGMENT_DIFFERENCES' | 'REMOVING_REDUNDANT_FEATURES_VIA_SQL', required
  - `data` AudienceSegmentation, required
    - `segId` string, required — The ID of the lookalike audience.
    - `audience_id_fs` string, required — The ID of the audience.
    - `status` 'PRESTART' | 'FINDING_FEATURES' | 'COLLECTING_IDS' | 'STAGING_DATA' | 'COMPLETED' | 'FAILED' | 'FITTING_SUPERVISED_MODEL' | 'BACKTESTING_SUPERVISED_MODEL' | 'CLUSTERING_RESULTS' | 'TRAINING_STACK' | 'PREDICTING_SUPERVISED_MODEL' | 'PREDICTING_STACK_MODEL' | 'RESCALING_RESULTS' | 'WRITING' | 'LOGGING_PROBABILITIES' | 'LOGGING_INFERENCE_SET_SIZE' | 'FINDING_OPTIMAL_K' | 'FINDING_CENTERS' | 'FINDING_SEGMENT_DIFFS' | 'FINDING_SEGMENT_DIFFERENCES' | 'REMOVING_REDUNDANT_FEATURES_VIA_SQL', required
    - `options` object — The options for the lookalike audience.
    - `featureImportance` object[] — The feature importance of the segmentation.
    - `ignoreColumns` string[], required — The passthrough columns of the lookalike model.
    - `numSegments` integer — The number of segments.
    - `segments` AudienceSegment[], required — The segments of the audience.
      - `name` string, required — The name of the segment.
      - `cluster_id` integer, required — The cluster ID of the segment.
      - `overview` object — The overview statistics of the segment.
      - `description` string — The description of the segment.
      - `topFactors` TopFactor[] — The top factors of the segment.
        - `name` string, required
        - `importance` number, required
        - `keyDifferences` object[], required
      - `bannerImagePath` string — The banner image path of the segment.
      - `aiSummary` AISummary[] — The AI summary of the segment.
        - `summary` string, required
        - `keyDifference` object, required
    - `execution_duration` number, nullable — The execution duration of the segmentation.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/akk/apis/fastapi.md) · [All operations](https://skmtc.net/akk/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/akk/fastapi/revisions/6662a407c637/schema)