Lists¶

User-defined lists let you organise followed accounts into named groups and read their posts as a dedicated timeline via get_list_timeline().

Server compatibility¶

Server	Support
Mastodon	✅ Full support
Pleroma / Akkoma	❌ Not supported — returns `404 Not Found` → raises `NotFoundError`
GotoSocial	❌ Not supported — returns `404 Not Found` → raises `NotFoundError`

All list management methods require authentication.

Managing lists¶

Get all lists¶

from longwei import APClient, UserList
import httpx

async with httpx.AsyncClient() as client:
    ap = await APClient.create(
        instance="mastodon.social",
        client=client,
        access_token="your_token",
    )
    lists: list[UserList] = await ap.get_lists()
    for lst in lists:
        print(f"{lst.id}: {lst.title}")

Create a list¶

lst: UserList = await ap.create_list(
    title="Close Friends",
    replies_policy="list",   # show replies from list members to each other
    exclusive=False,          # keep members in home timeline too
)
print(f"Created list {lst.id}: {lst.title}")

Get a single list¶

lst: UserList = await ap.get_list("12345")
print(lst.title, lst.replies_policy)

Update a list¶

lst = await ap.update_list(
    "12345",
    title="Best Friends",
    replies_policy="followed",
)

Delete a list¶

Deleting a list does not unfollow the accounts in it.

await ap.delete_list("12345")

Managing list members¶

Accounts must be followed by the authenticated user before they can be added to a list.

Get accounts in a list¶

from longwei import Account

accounts: list[Account] = await ap.get_list_accounts(
    "12345",
    limit=40,   # server default is 40; paginate for larger lists
)
for account in accounts:
    print(account.acct)

Supports cursor pagination via max_id, min_id, and since_id.

Add accounts to a list¶

await ap.add_list_accounts("12345", account_ids=["1", "2", "3"])

Remove accounts from a list¶

await ap.delete_list_accounts("12345", account_ids=["2"])

Reading a list timeline¶

Once a list is set up, read its timeline with the already-implemented get_list_timeline():

from longwei import Status

statuses: list[Status] = await ap.get_list_timeline("12345", limit=20)
for status in statuses:
    print(status.account.acct if status.account else "?", status.content)

`replies_policy` values¶

Value	Behaviour
`"followed"`	Show replies from list members to accounts you follow
`"list"`	Show replies from list members to other list members only
`"none"`	Do not show any replies in the list timeline

The server default when replies_policy is omitted is "list".

Exclusive lists (Mastodon 4.2+)¶

Setting exclusive=True hides list members' posts from the home timeline, keeping them only in the list timeline. This requires Mastodon 4.2 or later. On older servers the field is accepted but silently ignored.

lst = await ap.create_list(
    title="Work Accounts",
    exclusive=True,  # these posts won't appear in home timeline
)