Notifications

An API key reads its organization’s whole feed, so mark_all_read clears it for everyone. For work still running, use Jobs.

Each notification has a type, a title and message to show, and metadata whose keys depend on its type. Branch on type:

project_id and project_name are the dataset’s id and name.

list

One page of notifications, newest first.

Source: Notifications.list

for notification in client.notifications.list(unread_only=True, limit=25):
    print(notification.type, notification.title)
    if notification.type == "training_completed":
        print(notification.metadata["model_name"])
    client.notifications.mark_read(notification=notification.id)

pictograph notifications list --unread --limit 25

curl -s "https://api.pictograph.io/api/v1/developer/notifications?unread_only=true&limit=25&offset=0" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns list[Notification]

class Notification(BaseModel):
    """One of your notifications: a training run that finished, an export that is ready."""
    id: str
    organization_id: str
    user_id: str | None = None
    # Event type, such as 'training_completed' or 'export_completed'.
    type: str
    title: str
    message: str | None = None
    metadata: dict[str, Any] | None = None
    read: bool = False
    created_at: datetime

The REST answer carries the unread_count too.

unread_count

How many are unread, without the rows. Cheap enough to poll often.

Source: Notifications.unread_count

pending = client.notifications.unread_count()
if pending:
    print(pending, "new events")

pictograph notifications unread-count

curl -s "https://api.pictograph.io/api/v1/developer/notifications/unread-count" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns int

mark_read

Mark one notification read (marking it again does nothing).

Source: Notifications.mark_read

client.notifications.mark_read(notification="1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94")

pictograph notifications read 1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94

curl -s -X POST "https://api.pictograph.io/api/v1/developer/notifications/1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94/read" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

mark_all_read

Mark the whole feed read; it returns how many were unread.

Source: Notifications.mark_all_read

marked = client.notifications.mark_all_read()
print(marked, "notifications marked read")

pictograph notifications read-all

curl -s -X POST "https://api.pictograph.io/api/v1/developer/notifications/read-all" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns int

delete

Permanently remove a notification from the feed.

Source: Notifications.delete

client.notifications.delete(notification="1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94")

pictograph notifications delete 1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94

curl -s -X DELETE "https://api.pictograph.io/api/v1/developer/notifications/1a6e4f28-9b30-4c57-8d21-6f3b0a5e7c94" \
  -H "X-API-Key: $PICTOGRAPH_API_KEY"

Returns None

Polling pattern

Poll the count, and fetch the rows only when there are some:

import time

while True:
    if client.notifications.unread_count():
        for notification in client.notifications.list(unread_only=True):
            print(notification.type, notification.title, notification.metadata)
            client.notifications.mark_read(notification=notification.id)
    time.sleep(30)

Common errors