> ## 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 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: 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/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: >-
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)**.
required: true
schema:
type: string
SegmentIdPath:
name: id
in: path
description: The ID of the segment.
required: true
schema:
type: string
responses:
200_SegmentListV3:
description: >-
Successful retrieval of segments. Returns a list of 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 segments.
properties:
data:
type: array
description: Array of 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 segment in a list.
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).
type:
type: string
description: The type of the segment. This is used for internal classification.
example: ELASTIC_SEARCH
source:
type: string
description: The source of 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 segment that
conflicts with the request.
existing_cs_id:
type: string
description: >-
(Conflict errors only) The ID of the existing 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: >
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).
````