List sent notifications, with reach and reads

GET

/v1/notifications

Newest first. Each row carries stats (reached, read, read_rate, clicked, click_rate, and for a broadcast active_7d). status filters direct notifications by read state, or scheduled lists those waiting for their time. user_id lists what went to that user, groups included. unread_count is the project’s unread direct notifications.

Auth: Secret key only. The dashboard has the same operation under /v1/dashboard/notifications.

Authorizations

SecretApiKey

Parameters

Query Parameters

user_id

string

<= 256 characters

status

string

Allowed values: read unread all scheduled

audience

string

Allowed values: user users all

category

string

limit

integer

default: 20 >= 1 <= 100

cursor

string

next_cursor from the previous page.

Responses

200

Notifications

object

data

object

notifications

Array

object

string

Example

ntf_01J...

project_id

string

user_id

Set on a direct notification only.

string | null

audience

user: one user id. users: a group. all: everyone.

string

Allowed values: user users all

broadcast

boolean

title

string

body

string

action_url

string | null

icon

string

Allowed values: check warning info error

category

A short name the bell can show as a tab, such as billing.

string | null

/^[a-z][a-z0-9_-]{0,23}$/

actions

Up to two buttons. Each url is an http(s) URL or a path on your own site.

Array<object>

<= 2 items

object

label

required

string

<= 40 characters

url

required

string

<= 2048 characters

data

Anything your page needs with the item (at most 2,048 bytes as JSON). Never shown; the bell widget passes it in its events.

object | null

read_at

Direct notifications only; null on a group or a broadcast, which are read per person.

string | null

created_at

string format: date-time

visible_at

When it shows in bells: created_at, or the scheduled time.

string format: date-time

scheduled

Waiting for visible_at. Delete it to cancel; the month’s count is given back.

boolean

recipient_count

1 for a direct notification, the group’s size for a group, null for a broadcast.

integer | null

pinned

boolean

reactions

The reaction names people can pick in the bell; empty for none.

Array<string>

source

string

Allowed values: api changelog

changelog_entry_id

string | null

stats

reached: 1 for a direct notification; for a group, the people it went to; for a broadcast, the people whose bell asked for notifications after it showed (recorded at most once an hour per person, and never fewer than read); 0 while scheduled. read: the people who marked it read (a click or an archive counts). clicked: the people who clicked it or one of its buttons. read_rate and click_rate: over reached, three decimals, null while nobody was reached.

object

reached

integer

read

integer

read_rate

number | null

clicked

integer

click_rate

number | null

reactions

Reaction name to count, when it takes reactions.

object | null

active_7d

Broadcasts only: people whose bell asked in the last 7 days, to compare reached with. Null for direct and group sends.

integer | null

next_cursor

string | null

unread_count

integer

error

null

meta

object

400

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

401

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties

403

Error envelope. See error.code for the discriminator.

object

data

required

null

error

required

object

code

required

string

message

required

string

remediation

required

string

doc_url

string format: uri

param

string

request_id

string

meta

object

key

additional properties