> ## 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.
# Search Flows
> This API returns a paginated list of flows matching your filters. Send filters in the
request body — all are optional and combine with AND. Multi-valued filters (`status`,
`delivery_type`, `tags`) match ANY of the supplied values, and archived flows are excluded
unless `include_archived` is `true`.
Each response includes a `next_cursor`. To get the next page, send that value as the
`cursor` in your next request. Sorting is not supported in this version; results are
returned most recent first. Your API key must have the `campaigns:view` permission (see
[Authentication](/api/flows/flows-overview#authentication)).
#### Rate Limits
The rate limits are at the workspace level. A maximum of 10 requests per second, 100 requests per minute, and 6,000 requests per hour are allowed per workspace.
## OpenAPI
````yaml /api/flows/flows.yaml post /v5/flows/search
openapi: 3.0.0
info:
title: Flows
version: '5.0'
description: >
Use the Flows endpoints to list your flows, view the details of a single
flow (including its
versions and stages), and change a flow's status. These
endpoints read and control existing flows; they do not create them.
The Flows endpoints are in early access. MoEngage enhances these endpoints based on feedback during this period, but does not make breaking changes.
The API exposes the following endpoints:
- `POST /v5/flows/search` — paginated listing with filters (status, delivery
type, tags,
teams, name, creator, creation-date range).
- `GET /v5/flows/{flow_id}` — single flow detail. Use the optional
`version_no` query
parameter to view a specific version; the default is the last published version, or
the draft if none is published.
- `GET /v5/flows/{flow_id}/versions/{version_id}` — the details of a flow as
it was in a
specific version, identified by its ID.
- `PATCH /v5/flows/{flow_id}/status` — lifecycle transition (`pause`,
`resume`, `stop`,
`retire`) or the flow-level `archive` / `unarchive` toggle.
**Conventions**
- IDs are 24-character identifiers. `flow_id` identifies the flow;
`version_id` identifies one
of its versions.
- Every successful response uses the format `{response_id, type, data}`. The
`response_id`
echoes the `request_id` you send; if you omit it, the server uses the first 12 characters
of a system-generated UUID.
- Dates and times are in ISO 8601 UTC format (`YYYY-MM-DDThh:mm:ssZ`).
- The search endpoint returns results one page at a time. To fetch the next
page, send the
`next_cursor` from the previous response back as the `cursor` value.
**Permissions**
Flows reuse the `campaigns` permission for scope checks. Read endpoints
require the
`campaigns:view` permission; the status endpoint requires
`campaigns:create_manage`.
**Status Model**
Public flow statuses: `DRAFT`, `ACTIVE`, `SCHEDULED`, `PAUSED`, `STOPPED`,
`COMPLETED`,
`RETIRED`, `UNDER_REVIEW`, `REJECTED`. `archived` is a separate boolean flag
(it spans every version of the flow), not a status.
**Rate Limits**: The rate limits are at the workspace level. A maximum of 10
requests per second,
100 requests per minute, and 6,000 requests per hour are allowed per
workspace for the search,
get, and status endpoints.
Breaching any limit rejects the request with a `429` response.
servers:
- url: https://api-{dc}.moengage.com
variables:
dc:
default: '01'
description: >
MoEngage data center identifier. Replace it with the number assigned
to your account, such as 01 (US), 02 (EU), 03 (India), 04 (US), 05
(Singapore), or 06 (Indonesia). For example,
https://api-01.moengage.com. Data center 101 is not supported.
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
security:
- basicAuth: []
paths:
/v5/flows/search:
post:
tags:
- Flows
summary: Search Flows
description: >
This API returns a paginated list of flows matching your filters. Send
filters in the
request body — all are optional and combine with AND. Multi-valued
filters (`status`,
`delivery_type`, `tags`) match ANY of the supplied values, and archived
flows are excluded
unless `include_archived` is `true`.
Each response includes a `next_cursor`. To get the next page, send that
value as the
`cursor` in your next request. Sorting is not supported in this version;
results are
returned most recent first. Your API key must have the `campaigns:view`
permission (see
[Authentication](/api/flows/flows-overview#authentication)).
operationId: searchFlows
parameters:
- $ref: '#/components/parameters/XMoeTenantId'
- $ref: '#/components/parameters/XMoeRequestIdHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FlowSearchRequest'
examples:
defaultPage:
summary: First page, default filters
value:
limit: 20
byStatus:
summary: Filter by status
value:
status:
- ACTIVE
- PAUSED
limit: 20
byDeliveryType:
summary: Filter by delivery type
value:
delivery_type:
- EVENT_TRIGGERED
- PERIODIC
limit: 20
byName:
summary: Name substring match
value:
name: test
limit: 20
byCreationDateRange:
summary: Creation-date range
value:
creation_start_time: '2025-01-01T00:00:00Z'
creation_end_time: '2026-12-31T23:59:59Z'
limit: 20
nextPage:
summary: Fetch the next page with a cursor
value:
limit: 20
cursor: eyJpZCI6ICI2OWYxZGU4NGY5ZTQwMWEyZDdkOWE5MzEifQ==
responses:
'200':
description: Flows matching the filters.
headers:
X-MOE-Request-Id:
$ref: '#/components/headers/XMoeRequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/FlowSearchResponse'
example:
response_id: abc-701
type: flow
data:
flows:
- flow_id: 69f1de84f9e401a2d7d9a931
name: Welcome journey
status: ACTIVE
archived: false
delivery_type: EVENT_TRIGGERED
active_version_name: Version 2
tags:
- onboarding
created_at: '2026-01-05T10:00:00Z'
updated_at: '2026-02-01T09:30:00Z'
published_at: '2026-01-06T08:00:00Z'
created_by: agent@example.com
has_more: true
next_cursor: eyJpZCI6ICI2OWYxZGU4NGY5ZTQwMWEyZDdkOWE5MzEifQ==
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- basicAuth: []
components:
parameters:
XMoeTenantId:
name: X-MOE-Tenant-ID
in: header
required: false
description: >
Identifies the tenant/workspace making the request. Optional — when
omitted, the workspace is resolved from the Basic Auth credentials in
the `Authorization` header.
schema:
type: string
XMoeRequestIdHeader:
name: X-MOE-Request-Id
in: header
required: false
description: >
Client-supplied trace ID. The server echoes it in the `X-MOE-Request-Id`
response header and in `response_id`. If you omit it, the server
generates one.
schema:
type: string
schemas:
FlowSearchRequest:
type: object
description: >
Filters for listing flows. All filters are optional and combine with
AND. Enum filters (`status`, `delivery_type`) are case-insensitive.
properties:
request_id:
type: string
description: >-
Optional if supplied via the `X-MOE-Request-Id` header; echoed in
`response_id`.
status:
type: array
description: Keeps only flows whose status is in this set.
items:
$ref: '#/components/schemas/FlowStatusEnum'
delivery_type:
type: array
description: Keeps only flows that have one of these delivery types.
items:
$ref: '#/components/schemas/DeliveryTypeEnum'
tags:
type: array
description: The tag names to match; flows that carry any of them are kept.
items:
type: string
teams:
type: array
description: >
Team names. Required when the Flows-teams feature is enabled for the
workspace — omitting it or sending an empty list returns `400
VALIDATION_FAILED` ("teams is required when the team feature is
enabled"). When the feature is off, sending `teams` is rejected with
`400`.
items:
type: string
name:
type: string
description: Matches flows whose name contains this text, case-insensitively.
created_by:
type: array
description: The email addresses of the flow creators to filter by.
items:
type: string
format: email
creation_start_time:
type: string
description: >-
The inclusive lower bound on the creation time, in ISO 8601 UTC
format.
example: '2025-01-01T00:00:00Z'
creation_end_time:
type: string
description: >-
The inclusive upper bound on the creation time, in ISO 8601 UTC
format. It must be on or after `creation_start_time`.
example: '2026-12-31T23:59:59Z'
include_archived:
type: boolean
default: false
description: >-
`false` (default) excludes archived flows; `true` returns both
archived and non-archived.
limit:
type: integer
minimum: 1
maximum: 100
default: 20
description: The number of results returned per page.
cursor:
type: string
description: >-
The cursor from a previous page's `next_cursor`. Omit for the first
page.
FlowSearchResponse:
type: object
required:
- response_id
- type
- data
properties:
response_id:
type: string
description: >-
Echo of the `request_id` that you supplied, or a generated ID when
absent.
type:
type: string
enum:
- flow
data:
type: object
required:
- flows
- has_more
properties:
flows:
type: array
items:
$ref: '#/components/schemas/FlowSummary'
has_more:
type: boolean
description: Whether another page exists after this one.
next_cursor:
type: string
nullable: true
description: >-
Cursor to pass as `cursor` for the next page. Null on the last
page.
FlowStatusEnum:
type: string
description: >
Public lifecycle status of a flow (or of a specific version),
independent of the `archived` flag.
enum:
- DRAFT
- ACTIVE
- SCHEDULED
- PAUSED
- STOPPED
- COMPLETED
- RETIRED
- UNDER_REVIEW
- REJECTED
DeliveryTypeEnum:
type: string
description: Indicates how users enter the flow.
enum:
- ONE_TIME
- PERIODIC
- ON_FLOW_EXIT
- EVENT_TRIGGERED
- BUSINESS_EVENT_TRIGGERED
FlowSummary:
type: object
description: One flow as it appears in a search or list result.
required:
- flow_id
properties:
flow_id:
type: string
pattern: ^[a-f0-9]{24}$
description: The ID of the flow.
name:
type: string
description: Display name of the flow.
status:
allOf:
- $ref: '#/components/schemas/FlowStatusEnum'
description: Lifecycle status of the flow's active version.
archived:
type: boolean
default: false
description: >-
Whether the flow is archived (spans all versions). Independent of
`status`.
delivery_type:
$ref: '#/components/schemas/DeliveryTypeEnum'
active_version_name:
type: string
nullable: true
description: Display name of the active version, such as `Version 3`.
tags:
type: array
description: Tag names attached to the flow.
items:
type: string
created_at:
type: string
nullable: true
description: ISO 8601 UTC creation time.
updated_at:
type: string
nullable: true
description: ISO 8601 UTC last-update time of the active version.
published_at:
type: string
nullable: true
description: >-
ISO 8601 UTC publish time of the active version; null if never
published.
created_by:
type: string
nullable: true
description: Email of the flow's creator.
ErrorResponse:
type: object
required:
- error
- response_id
properties:
response_id:
type: string
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- VALIDATION_FAILED
- BAD_REQUEST
- NOT_FOUND
- UNAUTHORIZED
- FORBIDDEN
- RATE_LIMITED
- INTERNAL_ERROR
message:
type: string
target:
type: string
description: The component or field the error relates to.
details:
type: array
description: One entry per failing check.
items:
type: object
properties:
target:
type: string
message:
type: string
headers:
XMoeRequestId:
description: Echoed request ID. If you do not provide one, the server generates it.
schema:
type: string
responses:
BadRequest:
description: >
The request failed validation — for example, a bad filter value, a
malformed cursor, a non-integer `version_no`, an invalid date range, or
a `flow_id` that is actually a version ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: VALIDATION_FAILED
target: request
message: One or more request parameters failed validation.
details:
- target: request
message: Check the request parameters and try again.
Unauthorized:
description: Authentication failed (missing or invalid credentials).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: UNAUTHORIZED
message: Invalid or missing credentials.
details: []
Forbidden:
description: You do not have the required permission for this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-450
error:
code: FORBIDDEN
target: permission
message: You do not have the required permission for this operation.
details:
- target: permission
message: 'Required permission: campaigns:view'
RateLimited:
description: >-
Per-app rate limit exceeded. Retry after the interval indicated in the
`Retry-After` header.
headers:
Retry-After:
schema:
type: integer
description: Seconds until the rate-limit window resets.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: RATE_LIMITED
message: Rate limit exceeded for app key.
details: []
InternalServerError:
description: Unhandled server-side failure.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
response_id: abc-101
error:
code: INTERNAL_ERROR
message: Internal server error.
details: []
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**: On your MoEngage workspace, navigate to **Settings** →
**Account** → **API keys** and click **Create new key**. The tab lists
every API surface (Data, Segmentation, Push, Email, Campaigns,
Templates, and more) and exposes per-resource actions. Flows reuse the
Campaigns permissions — ensure the **View** checkbox (for the read
endpoints) and the **Create & Manage** checkbox (for Update Flow Status)
are selected.
For more information on authentication and getting your credentials,
refer to [Getting your
credentials](/api/introduction#getting-your-credentials).
Send the value in the `Authorization` header as `Basic` followed by
Base64-encoding of `appkey:apisecret` (workspace ID and API key).
````