---
title: "Retarget Segments"
method: POST
path: "/api/app-auto-gtm/projects/{project_id}/retarget"
tags: ["AppAutoGtm"]
---

# Retarget Segments

`POST /api/app-auto-gtm/projects/{project_id}/retarget`

Apply one targeting to a set of campaigns in a single request (T-286).

The "use the same targeting for every campaign" action: instead of the
browser firing one POST /segments/{id}/retarget per campaign, this writes the
same geo / company-size prompts to every selected campaign in ONE transaction,
then nudges each live campaign to re-search. Mirrors the project-scoped
save-templates / save-links "apply to all" pattern. Returns the per-campaign
action so the client can show the same breakdown the N-call path showed.

## Path parameters

- `project_id` integer, required

## Cookies

- `ex_access` string, nullable
- `ex_org` string, nullable

## Request body

- BulkRetargetRequest — Apply one targeting to a whole set of campaigns in a single request. The "use the same targeting for every campaign" path of the Targeting screen (T-286): one call carries the campaigns to apply to, instead of the browser firing one POST /segments/{id}/retarget per campaign. Inherits the geo / company-size prompts (+ trimming) from RetargetRequest; adds the segment set. Mirrors the project-scoped save-templates / save-links "apply to all" pattern.
  - `target_geo` string, nullable
  - `target_company_size` string, nullable
  - `segment_ids` integer[], required

## Response `200`

Successful Response

- BulkRetargetResponse
  - `results` RetargetResponse[], required
    - `segment` SegmentBrief, required
      - `name` string, required — Short campaign / segment name (2-4 words)
      - `pain` string — Core pain this ICP has (max ~10 words)
      - `use_case` string — What this ICP does with the product (max ~15 words)
      - `keywords` string — Comma-separated search keywords (5-8, lowercase, 1-3 words each)
      - `positive_criterias` string[] — Positive signals identifying this buyer (qualitative, 3-5 words each)
      - `negative_criterias` string[] — Disqualifying signals — look-alikes that are NOT a fit
      - `example_clients` string[] — Recognizable example companies that fit this ICP
      - `decision_maker` string — Who to reach at the prospect, framed by responsibility
      - `target_geo` string — Target geographies — country names, comma-separated
      - `target_company_size` string — Target company size — free-text prompt, e.g. "mid-market and enterprise", "startups under 50"
      - `id` integer, required
      - `description` string, required
      - `context` string
      - `daily_limit_usd` integer, required
      - `paused` boolean
      - `agent_turn_running` boolean
      - `instructions` string
      - `followup_instructions` string
      - `language` string
      - `target_url` string, nullable
      - `email_templates` object
      - `email_templates_version` integer
      - `updated_at` string
      - `people_count` integer
      - `preview_leads` PreviewLead[]
        - `id` string, required
        - `first_name` string, required
        - `last_name` string, required
        - `company` string, required
        - `lead_country_iso_2` string
        - `company_geo_country` string
        - `lead_headline` string
        - `profile_photo_url` string
        - `company_logo_url` string
        - `company_domain` string
      - `cached_previews` GeneratedEmailPayload[]
        - `id` string, required
        - `segment_id` integer, required
        - `lead_id` string, required
        - `touch_number` integer, required
        - `email_templates_version` integer, required
        - `subject` string, required
        - `body` string, required
        - `lead_first_name` string
        - `lead_last_name` string
        - `lead_company_name` string
        - `language_used` string
        - `language_reason` string
        - `highlights` EmailHighlight[]
          - `text` string, required
          - `kind` 'research' | 'ab_test' | 'instructions' | 'playbook', required
          - `title` string, required
          - `explanation` string, required
          - `sources` string[]
        - `cache_hit` boolean
      - `schedule` SegmentSchedule
        - `timezone` string, nullable
        - `working_hours` string, nullable
        - `days` string[], nullable
        - `use_system_schedule` boolean, nullable
        - `days_source` 'system' | 'user', nullable
        - `days_backfill_version` integer, nullable
      - `followup_rules` SegmentFollowupRules
        - `max_touches` integer
        - `delay_days` integer, nullable
        - `stop_on_reply` boolean, nullable
      - `report_frequency` string, nullable
      - `status_display` StatusDisplay — Unified status display object added to every client-facing segment payload. Computed once in _build_status_display; emitted as `status_display` on the wire. All legacy fields (status, paused, status_reason, agent_turn_running) remain unchanged for deploy-skew safety. Iteration-1 value vocabulary: not_started | searching | review | outreach | paused | budget_paused | listening | resuming | archived | error (`budget_paused` is the display-only $0-budget mask — see _ZERO_BUDGET_MASKED_STATES; no matching lifecycle status exists.)
        - `value` string, required
        - `label` string, required
        - `tone` string, required
        - `animated` boolean, required
        - `hint` string, required
        - `detail` string, required
        - `manual_start_blocked` boolean
    - `action` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/explee/apis/explee-api.md) · [All operations](https://skmtc.dev/explee/apis/explee-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/explee/explee-api/revisions/f169bc6e9447/schema)