---
title: "List notifications"
method: GET
path: "/notification"
tags: ["Notifications"]
---

# List notifications

`GET /notification`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/notification`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

Returns your company's in-app notifications, newest first, a page at a time. The Speak app shows the same list under **Notifications**.

#### Who sees what

An owner sees every notification in the company. A member of one or more user groups sees their own notifications, the ones written for the people in those groups, and the ones assigned to those groups. Anyone else sees every notification in the company. `filterUserId` narrows the list to one person.

`totalUnReadCount` always counts only your own unread notifications, whatever filters you send.

#### Categories and actions

`type` is the category of a notification and `action` is what happened. Send either as a filter. An unknown `type` is ignored and returns every category, while an unknown `action` matches nothing.

#### Labels and comments

- **Label library**: creating, editing, archiving, restoring or merging a label, or adding Speak label sets, writes `type` `label` with `mediaType` `label` for the person who made the change. `mediaId` holds the `labelId`.
- **Labels on a transcript**: applying, changing or removing labels writes `type` `label` with actions `created`, `updated` or `deleted`. `mediaId` and `mediaType` name the file.
- **Comments**: adding, editing, resolving, reopening or deleting a comment writes `type` `comment` for the person who did it, with actions `created`, `updated`, `resolved`, `reopened` or `deleted`.
- **Thread starters**: the person who started a thread also gets a `comment` notification when someone else replies (`replied`), resolves it (`resolved`) or reopens it (`reopened`). They are not told about their own replies, and people who are no longer active members are not told.
- **Dashboard share links**: turning labels or comments on or off on a dashboard's share link, or changing its modes or reviewer names, writes `type` `dashboard` with `mediaType` `dashboard`, and `mediaId` holds the `dashboardId`.

Changes made through a dashboard share link are written for the link's owner and end with "by <name> from a shared dashboard".

## Query parameters

- `page` integer
- `pageSize` integer
- `type` 'clip' | 'audio' | 'account' | 'automation' | 'embed' | 'integration' | 'magic prompt' | 'media' | 'payment' | 'presentation' | 'recorder' | 'survey' | 'subscription' | 'team' | 'text' | 'transcription' | 'translate' | 'video' | 'zapier' | 'meeting assistant' | 'google calendar' | 'outlook calendar' | 'auto reload' | 'folder' | 'fields' | 'assistant template' | 'knowledge base' | 'label' | 'comment' | 'dashboard'
- `action` 'analyzed' | 'created' | 'credit' | 'debit' | 'deleted' | 'export' | 'paid' | 'updated' | 'uploaded' | 'error' | 'failed' | 'cloned' | 'replied' | 'archived' | 'restored' | 'merged' | 'resolved' | 'reopened'
- `description` string
- `filterUserId` string
- `startDate` string, date-time
- `endDate` string, date-time
- `sortBy` 'createdAt' | 'description' | 'type' | 'isRead'
- `sortDir` 'asc' | 'desc'

## Response `200`

Success

- object
  - `status` 'success': `success` on every 2xx response.
  - `data` object
    - `totalCount` integer: How many notifications match the filters, across all pages.
    - `totalUnReadCount` integer: How many of your own notifications are unread.
    - `notificationList` object[]: This page of notifications.
      - `_id` string: Id of the notification.
      - `mediaId` string: Id of what the notification is about: a media file, or a `labelId` when `mediaType` is `label`, or a `dashboardId` when `mediaType` is `dashboard`. Left out when it is about nothing in particular.
      - `mediaType` string: What kind of thing `mediaId` names: `audio`, `video` or `text` for a file, `label` for a label or group, `dashboard` for a dashboard. Left out when there is no `mediaId`.
      - `description` string: What happened, in words you can show to a person.
      - `type` 'clip' | 'audio' | 'account' | 'automation' | 'embed' | 'integration' | 'magic prompt' | 'media' | 'payment' | 'presentation' | 'recorder' | 'survey' | 'subscription' | 'team' | 'text' | 'transcription' | 'translate' | 'video' | 'zapier' | 'meeting assistant' | 'google calendar' | 'outlook calendar' | 'auto reload' | 'folder' | 'fields' | 'assistant template' | 'knowledge base' | 'label' | 'comment' | 'dashboard': Category.
      - `action` 'analyzed' | 'created' | 'credit' | 'debit' | 'deleted' | 'export' | 'paid' | 'updated' | 'uploaded' | 'error' | 'failed' | 'cloned' | 'replied' | 'archived' | 'restored' | 'merged' | 'resolved' | 'reopened': What happened.
      - `amount` number: Amount on payment and credit notifications.
      - `transactionType` string: How a payment was made, on payment notifications.
      - `isRead` boolean: `true` once marked as read.
      - `createdAt` string, date-time: When it was written.
      - `updatedAt` string, date-time: When it last changed.
      - `user` object: The person the notification was written for. Left out when that user no longer exists.
        - `_id` string: User id.
        - `firstName` string: First name.
        - `lastName` string: Last name.
        - `picture` string: Profile picture URL, when set.

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)