> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Segment by ID > This API fetches a specific segment (File or Filter) by its ID. This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically. #### Rate Limit The rate limit is 100 requests/minute, 1000 requests/hour, and 4000 requests/day. ## OpenAPI ````yaml /api/custom-segments/custom-segments.yaml get /v3/custom-segments/{id} openapi: 3.0.3 info: title: MoEngage Segments API description: > Use the MoEngage Segments API to create, update, and manage your file and filter segments. - **v2 API:** Manage File Segments and segment lifecycle (Archive/Unarchive). - **v3 API:** Create, read, update, and list filter-based Segments. version: '3.0' servers: - url: https://api-{dc}.moengage.com description: MoEngage API Endpoint variables: dc: description: >- The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. default: '01' security: - basicAuth: [] tags: - name: File Segments description: > If you need to create segments by importing a large number of users, we recommend utilising the File segment API. This API allows you to easily generate a file segment by initiating a call to the file segment API endpoint. To proceed, you will need to compile a CSV file containing the relevant users (ensuring that the users are already present in MoEngage). It is essential to provide the public path of the file, which allows for downloading and identification of users in order to successfully create the file segment. Use the File Segment API to: * Create a new file segment * Add users to an existing segment * Remove users from an existing segment * Replace users from an existing segment - name: Manage Segments description: > Archiving and unarchiving through APIs makes it easy to retrieve and reuse segments whenever required for purposes such as A/B testing, maintaining regulatory compliance, and improving system performance. You can unarchive an archived segment to reuse it in campaigns and analysis without recreating it from scratch. x-mint: content: | Archived segments will not be shown beyond 180 days. - name: Filter Segments description: > If you need to create a segment based on the events or actions performed by your users on your application or website, the recommended approach is to use the filter segment API. With this API, you can create a segment by specifying the desired filter conditions. The filter segment API supports various operations, including create, update, get, and list, allowing you to effectively manage your segments based on specific criteria. x-mint: content: > ## Authentication Authentication is performed using Basic Auth. You must also provide the `MOE-APPKEY` header. ## Request Headers | Key | Required | Description | | :--- | :--- | :--- | | `Content-Type` | Yes | Set to `application/json`. | | `Authorization` | Yes | Basic Auth. `{"Authorization": "Basic Base64_ENCODED_WORKSPACEID_APIKEY="}` | | `MOE-APPKEY` | Yes | Your MoEngage App ID. Found in Settings -> Account -> APIs -> App ID. | paths: /v3/custom-segments/{id}: get: tags: - Filter Segments summary: Get Segment by ID description: This API fetches a specific segment (File or Filter) by its ID. operationId: getCustomSegment parameters: - $ref: '#/components/parameters/AppKeyHeader' - $ref: '#/components/parameters/DbNameHeaderOptional' - $ref: '#/components/parameters/SegmentIdPath' responses: '200': $ref: '#/components/responses/200_SegmentGetV3' '400': $ref: '#/components/responses/400_FilterSegmentGetError' '401': $ref: '#/components/responses/401_FilterSegmentError' '404': $ref: '#/components/responses/404_FilterSegmentError' '429': $ref: '#/components/responses/429_FilterSegmentRateLimitOnly' '500': $ref: '#/components/responses/500_FilterSegmentError' components: parameters: AppKeyHeader: name: MOE-APPKEY in: header description: > This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. You can send `MOE-DBNAME` with your database name instead of this header. The request must include one of the two. required: true schema: type: string DbNameHeaderOptional: name: MOE-DBNAME in: header description: > Your MoEngage database name. Send this as an alternative to `MOE-APPKEY` when you identify the workspace by database name. Omit it when `MOE-APPKEY` is already present. required: false schema: type: string SegmentIdPath: name: id in: path description: The ID of the segment. required: true schema: type: string responses: 200_SegmentGetV3: description: >- Successful retrieval of the segment. Returns the segment details including its filter definition and metadata. content: application/json: schema: $ref: '#/components/schemas/FilterSegmentResponseV3' example: data: name: active-users-segment id: 6388a97a02adb9071ca84ce9 created_time: '2022-12-01T13:17:46.409000' updated_time: '2022-12-01T13:17:46.450000' type: ELASTIC_SEARCH source: API description: Subscription Status is active (case insensitive) included_filters: filter_operator: and filters: - filter_type: user_attributes name: Subscription Status data_type: string operator: in value: - active negate: false case_sensitive: false excluded_filters: filter_operator: and filters: - filter_type: user_attributes name: is_test_user data_type: bool operator: is value: true negate: false response_id: WYanfieM type: custom_segment 400_FilterSegmentGetError: description: Bad Request. The segment ID passed in the request is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' examples: invalidBson: summary: Invalid Segment ID value: response_id: zUhCrqzu type: custom_segment error: code: Invalid request message: Invalid bson object-id passed in the request invalidAppKey: summary: Invalid App Key/DB Name value: response_id: FkrgtCVr type: custom_segment error: code: Request Error message: >- MoEngage Client not found. Please check values for headers - MOE-APPKEY or MOE-DBNAME 401_FilterSegmentError: description: >- Authentication Failure. The request failed authentication due to incorrect APP_KEY, APP_SECRET, or Authorization header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' examples: secretMismatch: summary: APP_SECRET Key Mismatch value: response_id: SzFRAzwK type: custom_segment error: code: Authentication required message: >- APP_SECRET key mismatch. Please login to the dashboard to verify key invalidAppKey: summary: Invalid APP_KEY in Auth value: response_id: bUfoyyhN type: custom_segment error: code: Authentication required message: Invalid APP_KEY used in Authentication Header 404_FilterSegmentError: description: >- Entity Not Found. The custom segment with the specified ID or name does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' example: response_id: UAMMfmuU type: custom_segment error: code: Entity Not Found message: >- Custom segment not found with the given id: 638a051185b6b50a018cacc 429_FilterSegmentRateLimitOnly: description: Too Many Requests. The API rate limit has been exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' example: response_id: OUUkHvcn type: custom_segment error: code: Too Many Requests message: 'API rate limit breached. Current limit: n/m mins' 500_FilterSegmentError: description: >- Internal Server Error. An unexpected error occurred on the MoEngage server. content: application/json: schema: $ref: '#/components/schemas/ServerErrorResponseV3' example: response_id: HKWwUkvM type: custom_segment error: code: Internal Server Error message: >- An unexpected error was encountered while processing this request. Please contact MoEngage Team schemas: FilterSegmentResponseV3: type: object description: Response schema for filter segment operations (create/update). properties: data: $ref: '#/components/schemas/FilterSegmentDataV3' description: Information about the segment. response_id: type: string description: A unique identifier for this API response. type: type: string description: The type of resource referenced in the response. example: custom_segment ErrorResponseV3: type: object description: Error response schema for client errors (4xx). properties: response_id: type: string description: A unique identifier for this API response. type: type: string description: The type of resource referenced in the response. example: custom_segment error: $ref: '#/components/schemas/ErrorDataV3' description: Details about the error that occurred. ServerErrorResponseV3: type: object description: Error response schema for server errors (5xx). properties: response_id: type: string description: A unique identifier for this API response. type: type: string description: The type of resource referenced in the response. example: custom_segment error: $ref: '#/components/schemas/ServerErrorDataV3' description: Details about the server error that occurred. FilterSegmentDataV3: type: object description: Detailed information about a segment. properties: name: type: string description: The name of the segment. id: type: string description: The unique identifier of the segment. created_time: type: string format: date-time description: The timestamp when the segment was created (ISO 8601 format). updated_time: type: string format: date-time description: >- The timestamp when the segment was last updated (ISO 8601 format). The updated time can change due to internally running services. type: type: string description: >- The type of the segment. This is used for internal classification. Fixed value for filter-based segments. example: ELASTIC_SEARCH source: type: string description: >- The source of segment creation. Fixed value for API-created segments. example: API description: type: string description: A textual description summarizing the segment definition. included_filters: $ref: '#/components/schemas/FilterGroupResponseV3' description: The filter criteria used to include users in this segment. excluded_filters: $ref: '#/components/schemas/FilterGroupResponseV3' description: >- The filter criteria used to exclude users from this segment. Present when `excluded_filters` was used while creating or updating the segment. ErrorDataV3: type: object description: Error details for client errors (4xx). properties: code: type: string description: >- A short error code that provides a brief explanation of the error (e.g., 'Invalid Request', 'Authentication required'). message: type: string description: A detailed error message describing why the request failed. ServerErrorDataV3: type: object description: Error details for server errors (5xx). properties: code: type: string description: >- A short error code indicating the type of server error (e.g., 'Internal Server Error'). message: type: string description: >- A detailed error message. For server errors, this typically advises contacting MoEngage support. FilterGroupResponseV3: type: object description: >- A logical grouping of filters as stored on the segment. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_operator: type: string description: The logical operator to combine the filters. enum: - and - or filters: type: array items: $ref: '#/components/schemas/FilterResponseV3' FilterResponseV3: description: >- A single stored filter criterion. The `filter_type` field selects the filter kind. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. oneOf: - $ref: '#/components/schemas/AttributeFilterResponseV3' - $ref: '#/components/schemas/ActionFilterResponseV3' - $ref: '#/components/schemas/AffinityFilterResponseV3' - $ref: '#/components/schemas/CustomSegmentFilterResponseV3' - $ref: '#/components/schemas/NestedFiltersResponseV3' discriminator: propertyName: filter_type mapping: user_attributes: $ref: '#/components/schemas/AttributeFilterResponseV3' actions: $ref: '#/components/schemas/ActionFilterResponseV3' psychographic_event: $ref: '#/components/schemas/AffinityFilterResponseV3' custom_segments: $ref: '#/components/schemas/CustomSegmentFilterResponseV3' nested_filters: $ref: '#/components/schemas/NestedFiltersResponseV3' AttributeFilterResponseV3: title: User Property Filter type: object description: >- A stored user profile attribute filter (`filter_type: "user_attributes"`), or an event attribute filter inside an event's `attributes` block. The API omits `filter_type` on event attribute filters when it echoes them back. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_type: type: string description: >- Present as `user_attributes` on user property filters. Omitted on event attribute filters. enum: - user_attributes name: type: string description: >- The internal name of the user attribute (for example, `last_purchase_date`). data_type: type: string description: The data type of the attribute. enum: - string - double - bool - datetime - geopoint - array_string - array_double - object - array_object category: type: string description: >- The attribute group the attribute belongs to (for example, `Tracked Custom Attribute`). operator: type: string description: The comparison operator. enum: - is - in - contains - containsInTheFollowing - startsWith - startsWithInTheFollowing - endsWith - endsWithInTheFollowing - exists - lessThan - greaterThan - between - true - before - after - inTheLast - inTheNext - today negate: type: boolean description: Set to `true` to invert the filter (NOT condition). default: false value: description: The comparison value. oneOf: - type: string - type: number - type: boolean - type: array items: oneOf: - type: string - type: number value1: description: >- The second bound for range comparisons: - Upper bound when `operator` is `between` (numeric and datetime types). - Longitude for `geopoint`. oneOf: - type: string - type: number case_sensitive: type: boolean description: Applies to `string` and `array_string`. default: false value_type: type: string description: Applies to `datetime` only. enum: - absolute - relative_past - relative_future extract_type: type: string description: Applies to `datetime` only. enum: - time_of_the_day - day_of_the_week - day_of_the_month - month_of_the_year - date_month_of_the_year radius: type: number description: Applies to `geopoint` only. array_filter_type: type: string description: Applies to `array_string` and `array_double`. enum: - any_of - all_of filter_operator: type: string description: Applies to `object` and `array_object`. enum: - and - or filters: type: array description: Applies to `object` and `array_object`. items: $ref: '#/components/schemas/AttributeFilterResponseV3' is_dynamic_value: type: boolean description: >- Set to `true` when `value` references another user attribute rather than a literal. default: false dynamic_attribute_type: type: string description: Required when `is_dynamic_value` is `true`. enum: - string - double - bool - datetime ActionFilterResponseV3: title: User Behavior Filter type: object description: >- A stored event filter (`filter_type: "actions"`). Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_type: type: string description: Must be `actions` for a User Behavior filter. enum: - actions action_name: type: string description: The internal name of the event to filter on. project_name: type: string description: Optional. executed: type: boolean description: >- Set to `true` to match users who performed the event; `false` to match users who did not. execution: type: object description: The frequency condition for the event. properties: type: type: string enum: - atleast - exactly - atmost - firstTime - lastTime count: type: integer format: int32 description: Required for `atleast`, `exactly`, and `atmost`. primary_time_range: type: object description: The time window during which the event must have been performed. properties: type: type: string enum: - inTheLast - between - true - before - after value_type: type: string description: >- Whether `value` is an ISO 8601 date (`absolute`) or an integer offset (`relative_past`). enum: - absolute - relative_past value: description: >- Integer count of `period_unit` for relative ranges, or an ISO 8601 date string for absolute ranges. value1: description: End bound for `between`. period_unit: type: string description: The unit of time. enum: - hours - days - weeks - months attributes: $ref: '#/components/schemas/ActionAttributeFilterGroupResponseV3' description: >- Sub-filters on the event's own attributes — for example, `purchase` where `product_category` is `Electronics`. aggregation_attributes: type: object description: Optional aggregation block. properties: filter_operator: type: string enum: - and - or filters: type: array items: $ref: '#/components/schemas/AggregationAttributeFilterResponseV3' AffinityFilterResponseV3: title: User Affinity Filter type: object description: >- A stored affinity filter (`filter_type: "psychographic_event"`). Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_type: type: string enum: - psychographic_event description: Must be `psychographic_event` for a User Affinity filter. action_name: type: string description: The internal name of the event to evaluate affinity on. executed: type: boolean description: Whether the user has performed the event. default: true execution: type: object description: The frequency condition for the event. properties: type: type: string enum: - atleast - exactly - atmost - firstTime - lastTime count: type: integer description: Required for `atleast`, `exactly`, and `atmost`. operator_type: type: string description: The affinity matching mode. enum: - predominant - minimum - top - bottom percent_of_times: type: integer minimum: 1 maximum: 100 description: Required when `operator_type` is `minimum`. percent_of_users: type: integer minimum: 1 maximum: 100 description: Required when `operator_type` is `top` or `bottom`. psychographic_attributes: type: object description: >- Defines what the affinity is about (for example, `product_category is "Electronics"`). properties: filter_operator: type: string enum: - and - or filters: type: array items: $ref: '#/components/schemas/PsychographicAttributeFilterResponseV3' attributes: $ref: '#/components/schemas/ActionAttributeFilterGroupResponseV3' description: >- Optional additional event-attribute filters to narrow which event occurrences count toward the affinity. primary_time_range: type: object description: The time window over which affinity is evaluated. properties: type: type: string description: The type of time window. value_type: type: string enum: - absolute - relative_past description: >- Whether the window is expressed as relative day counts (`days`/`days1`) or absolute dates (`from`/`to`). days: type: integer description: Relative windows only. days1: type: integer description: Relative windows only. from: type: string format: date-time description: Absolute windows only. to: type: string format: date-time description: Absolute windows only. CustomSegmentFilterResponseV3: title: Custom Segment Filter type: object description: >- A stored reference to a saved segment (`filter_type: "custom_segments"`). Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_type: type: string enum: - custom_segments description: Must be `custom_segments` for a Custom Segment filter. id: type: string description: The unique ID of the saved segment. name: type: string description: Display label for the segment. NestedFiltersResponseV3: title: Nested Filters (AND/OR Group) type: object description: >- A stored AND/OR group container (`filter_type: "nested_filters"`). Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_type: type: string enum: - nested_filters description: Must be `nested_filters` for a logical group container. filter_operator: type: string enum: - and - or description: The logical operator combining the filters in this group. filters: type: array description: The filters within this group. items: $ref: '#/components/schemas/FilterResponseV3' ActionAttributeFilterGroupResponseV3: type: object description: >- Stored attribute filters scoped to an event's own properties. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: filter_operator: type: string description: The logical operator to combine the attribute filters. enum: - and - or filters: type: array description: Attribute filters scoped to the event's properties. items: $ref: '#/components/schemas/AttributeFilterResponseV3' AggregationAttributeFilterResponseV3: title: Aggregation Condition type: object description: >- A stored aggregation condition on a numeric event attribute. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: attribute_name: type: string description: The name of the numeric event attribute to aggregate. data_type: type: string enum: - double description: The data type of the aggregated attribute. aggregation_type: type: string enum: - sum - avg - min - max - median description: >- The aggregation function to apply across the user's matching event occurrences. operator: type: string enum: - is - between - lessThan - greaterThan description: The comparison operator. value: type: number description: The numeric threshold to compare the aggregated result against. value1: type: number description: The upper bound. negate: type: boolean description: Set to `true` to invert the comparison. default: false is_dynamic_value: type: boolean description: >- Set to `true` when `value` is a business event personalization token rather than a literal number. default: false comparator: type: string enum: - change - percentageChange description: >- Compares the aggregate against an earlier window instead of a fixed threshold. base_time_range: type: object description: The earlier window to compare against. properties: type: type: string enum: - previousPeriod - between description: The kind of base window. value: type: string format: date-time description: Start of the base window. value1: type: string format: date-time description: End of the base window. PsychographicAttributeFilterResponseV3: title: Psychographic Attribute Filter type: object description: >- A stored attribute filter inside `psychographic_attributes`. Fields mirror what was supplied when the segment was created or updated. See the Create Filter Segment request reference for the full field rules. properties: name: type: string description: >- The internal name of the event attribute the affinity is evaluated on. data_type: type: string description: The data type of the attribute. enum: - string - double category: type: string description: The attribute group the attribute belongs to. operator: type: string description: The comparison operator. enum: - is - in - contains - startsWith - endsWith - exists - lessThan - greaterThan - between negate: type: boolean description: Set to `true` to invert the filter (NOT condition). default: false value: description: The comparison value. oneOf: - type: string - type: number - type: array items: oneOf: - type: string - type: number value1: type: number description: The upper bound when `operator` is `between`. case_sensitive: type: boolean description: Applies to `string`. default: false extract_type: type: string description: >- Applies to the four time-based affinity filters only, where `name` is `moe_user_datetime` and `category` is `Time Attributes`. enum: - time_of_the_day - day_of_the_week - day_of_the_month - month_of_the_year securitySchemes: basicAuth: type: http scheme: basic description: > Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'. - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. - **Password**: Use your API Key, which you can find within the **Data** tile. For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials). ````