> ## Documentation Index
> Fetch the complete documentation index at: https://moengage-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Segments Overview

> Create, update, and manage your file-based and filter-based segments using the MoEngage Custom Segments API.

## Overview

The MoEngage Custom Segments API allows you to programmatically manage your audience segments. This suite includes the **v2 API** for handling high-volume file-based segments and segment lifecycles, and the **v3 API** for dynamic, filter-based custom segments.

## Custom Segment API Endpoints

The Custom Segments API is a collection of the following endpoints:

### File Segments (v2)

* [Create File Segment](https://moengage.mintlify.app/api/custom-segments--file/create-file-segment)
* [Add Users to File Segment](https://moengage.mintlify.app/api/custom-segments--file/add-users-to-file-segment)
* [Remove Users from File Segment](https://moengage.mintlify.app/api/custom-segments--file/remove-users-from-file-segment)
* [Replace Users in File Segment](https://moengage.mintlify.app/api/custom-segments--file/replace-users-from-file-segment)

### Segment Lifecycle (v2)

* [Archive Custom Segment](https://moengage.mintlify.app/api/custom-segments--lifecycle/archive-custom-segment)
* [Unarchive Custom Segment](https://moengage.mintlify.app/api/custom-segments--lifecycle/unarchive-custom-segment)

### Filter Segments (v3)

* [List Custom Segments](https://moengage.mintlify.app/api/custom-segments--filters/list-custom-segments)
* [Create Filter Segment](https://moengage.mintlify.app/api/custom-segments--filters/create-filter-segment)
* [Get Custom Segment by ID](https://moengage.mintlify.app/api/custom-segments--filters/get-custom-segment-by-id)
* [Update Filter Segment](https://moengage.mintlify.app/api/custom-segments--filters/update-filter-segment)

## Segment Types

| Type               | Description                                                   | Best For                                                   |
| :----------------- | :------------------------------------------------------------ | :--------------------------------------------------------- |
| **File Segment**   | Created by importing a CSV file of unique user identifiers.   | Large, static lists or external data imports.              |
| **Filter Segment** | Created based on user attributes or real-time actions/events. | Dynamic targeting based on user behavior and profile data. |

## Usage Limits & Guidelines

### File Segment Limits

| Rate Limit Name           | Limit Value                                        |
| :------------------------ | :------------------------------------------------- |
| **Total Active Segments** | Maximum of 1000 active custom segments per client. |
| **Operations per Hour**   | 10 operations (create/add/remove) per hour.        |
| **Users per Day**         | 2 million users uploaded via File Segment per day. |
| **File Size**             | Maximum 150 MB per CSV file.                       |

## FAQs

### Filter-Based Segments

<AccordionGroup>
  <Accordion title="How can I generate the payload for custom segment creation?">
    You can generate the payload directly from the MoEngage Dashboard. Navigate to **Test & Debug** -> **Segment Payload**, choose your filters, and click **Generate Payload**.
  </Accordion>

  <Accordion title="How do I get the ID of a custom segment I created earlier but didn't save?">
    Use the **List Custom Segment API** with the `name` query parameter to filter and retrieve the unique ID of the desired segment.
  </Accordion>

  <Accordion title="Why am I getting a 409 Conflict error even with a different name?">
    Both the name and the definition (filters) of a custom segment must be unique. If the definition matches an existing segment, the API returns a 409 Conflict.
  </Accordion>

  <Accordion title="How do I know which existing segment is conflicting?">
    In the case of a 409 error, the response payload includes the `existing_cs_name` and `existing_cs_id` of the conflicting segment.
  </Accordion>

  <Accordion title="How do I increase the rate limits?">
    Please connect with your account manager.
  </Accordion>
</AccordionGroup>

### File-Based Segments

<AccordionGroup>
  <Accordion title="Why does my new segment show zero users immediately after creation?">
    Segment processing is asynchronous. MoEngage first creates the segment container (showing zero users) and then processes the file. The count will update once processing is complete.
  </Accordion>

  <Accordion title="Can I update a file segment using filter conditions?">
    No. File segments can only be updated (add/remove/replace) via the File Segment API using CSV imports. For attribute-based updates, use Filter Segments.
  </Accordion>
</AccordionGroup>

### Segment Lifecycle

<AccordionGroup>
  <Accordion title="What is the benefit of archiving a segment instead of deleting it?">
    Archiving allows you to reuse segments for A/B testing or historical analysis without recreating them from scratch, while keeping your active segment list within the 1000-segment limit.
  </Accordion>
</AccordionGroup>