> ## 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.
# Get Custom Segment by ID
> Fetches a specific custom segment (File or Filter) by its ID.
**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 Custom Segments API
description: >
Use the MoEngage Custom 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 Custom Segments.
version: '3.0'
servers:
- url: https://api-{dc}.moengage.com
description: MoEngage API Endpoint
variables:
dc:
description: Your account's Data Center (e.g., 01, 02, 03).
default: '01'
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
security:
- basicAuth: []
tags:
- name: Custom Segments - File
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 Custom File Segment API to:
* Create a new Custom File Segment
* Add Users to an existing Custom Segment
* Remove Users from an existing Custom Segment
* Replace Users from an existing Custom Segment
- name: Custom Segments - Lifecycle
description: >
Archiving and unarchiving through APIs makes it easy to retrieve and reuse
custom segments whenever required for purposes such as A/B testing,
maintaining regulatory compliance, and improving system performance.
You can access the archived segments and utilize them to analyze and
market campaigns without the need to recreate them from scratch.
x-mint:
content: |
Archived segments will not be shown beyond 180 days.
- name: Custom Segments - Filters
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 custom
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. |
## FAQs
You can simply generate the payload from the MoEngage dashboard. Log in to the MoEngage dashboard and navigate to the **Test & Debug** -> **Segment Payload section**. Choose your filters and click on **Generate Payload**.
You can use the LIST Custom Segment API with the name query param filter to get the id of the custom segment.
Both the name and the definition of a custom segment are unique. If the definition of the custom segment in the request matches an existing segment, we return a conflict 409 error.
In the case of 409 Conflict, we return a conflicting name/id in the response payload. You can check the payload to get the existing custom segment with the same definition.
paths:
/v3/custom-segments/{id}:
get:
tags:
- Custom Segments - Filters
summary: Get Custom Segment by ID
description: Fetches a specific custom segment (File or Filter) by its ID.
operationId: getCustomSegment
parameters:
- name: Content-Type
in: header
required: true
schema:
type: string
example: application/json
description: Set the Content-Type header to application/json.
- $ref: '#/components/parameters/AppKeyHeader'
- $ref: '#/components/parameters/SegmentIdPath'
responses:
'200':
$ref: '#/components/responses/200_SegmentListV3'
'400':
$ref: '#/components/responses/400_FilterSegmentError'
'401':
$ref: '#/components/responses/401_FilterSegmentError'
'429':
$ref: '#/components/responses/429_FilterSegmentRateLimitOnly'
'500':
$ref: '#/components/responses/500_FilterSegmentError'
components:
parameters:
AppKeyHeader:
name: MOE-APPKEY
in: header
description: The Workspace ID (APP ID) of your MoEngage account.
required: true
schema:
type: string
SegmentIdPath:
name: id
in: path
description: The ID of the custom segment.
required: true
schema:
type: string
responses:
200_SegmentListV3:
description: >-
Successful retrieval of custom segments. Returns a list of custom
segments matching the query criteria. An empty list is returned if no
segments match.
content:
application/json:
schema:
$ref: '#/components/schemas/SegmentListResponseV3'
example:
data:
- name: api_test_7
id: 6388a97a02adb9071ca84ce9
created_time: '2022-12-01T13:17:46.409000'
type: ELASTIC_SEARCH
source: API
response_id: WYanfieM
type: custom_segment
400_FilterSegmentError:
description: >-
Bad Request. The request is invalid due to missing required parameters,
invalid parameter format, or malformed request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseV3'
examples:
invalidFormat:
summary: Invalid Request Format
value:
response_id: xFyVHeOr
type: custom_segment
error:
code: Invalid request
message: >-
Invalid request format. Please check the documentation to
ensure that the request has been formed correctly.
invalidName:
summary: Invalid Segment Name
value:
response_id: XtVyUnlJ
type: custom_segment
error:
code: Invalid Request
message: >-
Invalid request. Please ensure that the filters are correct
and the custom-segment name doesn't contain HTML
characters/only whitespaces.
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
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:
SegmentListResponseV3:
type: object
description: Response schema for listing custom segments.
properties:
data:
type: array
description: Array of custom segments matching the query criteria.
items:
$ref: '#/components/schemas/SegmentListItemV3'
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.
SegmentListItemV3:
type: object
description: Summary information about a custom segment in a list.
properties:
name:
type: string
description: The name of the custom segment.
id:
type: string
description: The unique identifier of the custom segment.
created_time:
type: string
format: date-time
description: The timestamp when the custom segment was created (ISO 8601 format).
type:
type: string
description: >-
The type of the custom segment. This is used for internal
classification.
example: ELASTIC_SEARCH
source:
type: string
description: The source of custom segment creation.
example: API
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.
existing_cs_name:
type: string
description: >-
(Conflict errors only) The name of the existing custom segment that
conflicts with the request.
existing_cs_id:
type: string
description: >-
(Conflict errors only) The ID of the existing custom segment that
conflicts with the request.
actual_count:
type: integer
description: (Rate limit errors only) The actual count of segments or requests.
limit:
type: integer
description: (Rate limit errors only) The maximum allowed limit.
required:
- code
- message
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.
required:
- code
- message
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >
Basic Authentication using your **Workspace ID** (as username) and
**Data API Key** (as password) from the MoEngage Dashboard.
````