List notifications for an account

post

https://api.convert.com/api/v2/accounts/{account_id}/notifications

Retrieves notification records for the specified account.
Only notifications with status: delivered are returned. Results are paginated and support filtering by project,
entity, type, channel, and read state. When onlyCount is true, the response is { "data": <total> } with no
notification items or pagination. Notifications are retained for 30 days and are automatically deleted after that period.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

Body Params

results_per_page

integer | null

0 to 50

Defaults to 30

Specifies the maximum number of items to return in a single page of results.
Used for pagination. Default is 30, maximum is 50.

sort_direction

string | null

enum

Defaults to desc

The direction for sorting the list results, based on the sort_by field.

asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
desc: Descending order (e.g., Z-A, 10-1, newest to oldest).
Defaults to desc (newest/highest first) if not specified.

Allowed:

onlyCount

boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count)
and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

sort_by

string | null

enum

Defaults to delivered_at

Field to sort notifications by.

Allowed:

page

integer

≥ 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60.
Defaults to 1 if not specified.

projects

array of integers | null

Project IDs list to be used to filter notifications

projects

entity_type

string | null

enum

Entity that a notification relates to.

Allowed:

entity_id

≥ 1

Filter by one or more related entity IDs. Depends on entity_type:
experience ID when entity_type is experience, project ID when entity_type is account.
Combine with entity_type when filtering a specific entity kind; use projects to filter by project across types.

types

array of objects | null

Filter by notification types.

types

channels

array of objects | null

Filter by delivery channels.

channels

Allowed:

is_read

boolean | null

When true, return only read notifications; when false, only unread.

string | null

A search string that would be used to search against notification title and body

only

array of objects | null

Only retrieve notifications with the given ids.

only

except

array of objects

length ≤ 10

Except notifications with the given ids.

except

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Paginated list of notifications for an account, or { "data": <count> } when onlyCount is true.

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.