0
# Account Management
1
2
User account operations including profile management, following/blocking relationships, and account discovery. Provides comprehensive tools for managing social connections and user interactions on Mastodon.
3
4
## Capabilities
5
6
### Account Information
7
8
Retrieve detailed information about user accounts, including profiles, statistics, and verification status.
9
10
```python { .api }
11
def account(self, id: int) -> dict:
12
"""
13
Get account information by ID.
14
15
Args:
16
id: Account ID
17
18
Returns:
19
Dictionary containing account details (username, display_name, followers_count, etc.)
20
"""
21
22
def accounts(self, ids: list) -> list:
23
"""
24
Get multiple accounts by IDs (Mastodon 4.3.0+).
25
26
Args:
27
ids: List of account IDs
28
29
Returns:
30
List of account dictionaries
31
"""
32
33
def account_verify_credentials(self) -> dict:
34
"""
35
Get information about the authenticated user's own account.
36
37
Returns:
38
Dictionary containing own account details with additional private fields
39
"""
40
41
def me(self) -> dict:
42
"""
43
Alias for account_verify_credentials().
44
45
Returns:
46
Dictionary containing own account details
47
"""
48
49
def account_lookup(self, acct: str) -> dict:
50
"""
51
Look up account by webfinger address (username@domain).
52
53
Args:
54
acct: Account address in format username@domain.tld
55
56
Returns:
57
Dictionary containing account information
58
"""
59
```
60
61
### Account Content & Relationships
62
63
Access account-related content including statuses, followers, following lists, and relationship status.
64
65
```python { .api }
66
def account_statuses(
67
self,
68
id: int,
69
only_media: bool = False,
70
pinned: bool = False,
71
exclude_replies: bool = False,
72
exclude_reblogs: bool = False,
73
tagged: str = None,
74
max_id: int = None,
75
min_id: int = None,
76
since_id: int = None,
77
limit: int = 20
78
) -> list:
79
"""
80
Get statuses posted by an account.
81
82
Args:
83
id: Account ID
84
only_media: Only return statuses with media attachments
85
pinned: Only return pinned statuses
86
exclude_replies: Skip reply statuses
87
exclude_reblogs: Skip reblogged statuses
88
tagged: Only return statuses tagged with this hashtag
89
max_id: Return results older than this ID
90
min_id: Return results newer than this ID
91
since_id: Return results newer than this ID
92
limit: Maximum number of results (default 20, max 40)
93
94
Returns:
95
List of status dictionaries
96
"""
97
98
def account_following(
99
self,
100
id: int,
101
max_id: int = None,
102
min_id: int = None,
103
since_id: int = None,
104
limit: int = 40
105
) -> list:
106
"""
107
Get accounts followed by the specified account.
108
109
Args:
110
id: Account ID
111
max_id: Return results older than this ID
112
min_id: Return results newer than this ID
113
since_id: Return results newer than this ID
114
limit: Maximum number of results (default 40, max 80)
115
116
Returns:
117
List of account dictionaries
118
"""
119
120
def account_followers(
121
self,
122
id: int,
123
max_id: int = None,
124
min_id: int = None,
125
since_id: int = None,
126
limit: int = 40
127
) -> list:
128
"""
129
Get accounts following the specified account.
130
131
Args:
132
id: Account ID
133
max_id: Return results older than this ID
134
min_id: Return results newer than this ID
135
since_id: Return results newer than this ID
136
limit: Maximum number of results (default 40, max 80)
137
138
Returns:
139
List of account dictionaries
140
"""
141
142
def account_relationships(self, id: list) -> list:
143
"""
144
Get relationship status with one or more accounts.
145
146
Args:
147
id: Account ID or list of account IDs
148
149
Returns:
150
List of relationship dictionaries containing following, followed_by, blocking, etc.
151
"""
152
153
def account_lists(self, id: int) -> list:
154
"""
155
Get lists containing the specified account.
156
157
Args:
158
id: Account ID
159
160
Returns:
161
List of list dictionaries
162
"""
163
164
def account_familiar_followers(self, id: list) -> list:
165
"""
166
Get familiar followers for accounts (mutual connections).
167
168
Args:
169
id: Account ID or list of account IDs
170
171
Returns:
172
List of familiar follower information
173
"""
174
```
175
176
### Account Actions
177
178
Follow, unfollow, block, mute, and perform other relationship actions with accounts.
179
180
```python { .api }
181
def account_follow(
182
self,
183
id: int,
184
reblogs: bool = True,
185
notify: bool = False
186
) -> dict:
187
"""
188
Follow an account.
189
190
Args:
191
id: Account ID to follow
192
reblogs: Show reblogs from this account in timeline
193
notify: Get notifications when this account posts
194
195
Returns:
196
Relationship dictionary with updated status
197
"""
198
199
def account_unfollow(self, id: int) -> dict:
200
"""
201
Unfollow an account.
202
203
Args:
204
id: Account ID to unfollow
205
206
Returns:
207
Relationship dictionary with updated status
208
"""
209
210
def account_remove_from_followers(self, id: int) -> dict:
211
"""
212
Remove an account from your followers (soft block).
213
214
Args:
215
id: Account ID to remove
216
217
Returns:
218
Relationship dictionary with updated status
219
"""
220
221
def account_block(self, id: int) -> dict:
222
"""
223
Block an account.
224
225
Args:
226
id: Account ID to block
227
228
Returns:
229
Relationship dictionary with updated status
230
"""
231
232
def account_unblock(self, id: int) -> dict:
233
"""
234
Unblock an account.
235
236
Args:
237
id: Account ID to unblock
238
239
Returns:
240
Relationship dictionary with updated status
241
"""
242
243
def account_mute(
244
self,
245
id: int,
246
notifications: bool = True,
247
duration: int = None
248
) -> dict:
249
"""
250
Mute an account.
251
252
Args:
253
id: Account ID to mute
254
notifications: Also mute notifications from this account
255
duration: Duration in seconds (0 = indefinite)
256
257
Returns:
258
Relationship dictionary with updated status
259
"""
260
261
def account_unmute(self, id: int) -> dict:
262
"""
263
Unmute an account.
264
265
Args:
266
id: Account ID to unmute
267
268
Returns:
269
Relationship dictionary with updated status
270
"""
271
```
272
273
### Profile Management
274
275
Update and manage your own profile information including display name, bio, avatar, and custom fields.
276
277
```python { .api }
278
def account_update_credentials(
279
self,
280
display_name: str = None,
281
note: str = None,
282
avatar: str = None,
283
avatar_mime_type: str = None,
284
header: str = None,
285
header_mime_type: str = None,
286
locked: bool = None,
287
bot: bool = None,
288
discoverable: bool = None,
289
fields_attributes: list = None,
290
source: dict = None,
291
indexable: bool = None
292
) -> dict:
293
"""
294
Update profile information for the authenticated account.
295
296
Args:
297
display_name: Display name for profile
298
note: Profile bio/description (HTML allowed)
299
avatar: Avatar image file path or file-like object
300
avatar_mime_type: MIME type of avatar image
301
header: Header image file path or file-like object
302
header_mime_type: MIME type of header image
303
locked: Require approval for new followers
304
bot: Mark account as automated/bot account
305
discoverable: Allow account to be discovered in directory
306
fields_attributes: List of profile field dictionaries with 'name' and 'value'
307
source: Source settings (privacy, sensitive, language)
308
indexable: Allow indexing by search engines
309
310
Returns:
311
Updated account dictionary
312
"""
313
314
def account_delete_avatar(self) -> dict:
315
"""
316
Delete the profile avatar image (Mastodon 4.2.0+).
317
318
Returns:
319
Updated account dictionary
320
"""
321
322
def account_delete_header(self) -> dict:
323
"""
324
Delete the profile header image (Mastodon 4.2.0+).
325
326
Returns:
327
Updated account dictionary
328
"""
329
```
330
331
### Account Endorsements & Notes
332
333
Endorse accounts and manage private notes on user profiles.
334
335
```python { .api }
336
def account_pin(self, id: int) -> dict:
337
"""
338
Endorse (pin) an account to your profile.
339
340
Args:
341
id: Account ID to endorse
342
343
Returns:
344
Relationship dictionary with endorsement status
345
"""
346
347
def account_endorse(self, id: int) -> dict:
348
"""
349
Alias for account_pin().
350
351
Args:
352
id: Account ID to endorse
353
354
Returns:
355
Relationship dictionary with endorsement status
356
"""
357
358
def account_unpin(self, id: int) -> dict:
359
"""
360
Remove endorsement (unpin) from an account.
361
362
Args:
363
id: Account ID to remove endorsement from
364
365
Returns:
366
Relationship dictionary with updated status
367
"""
368
369
def account_unendorse(self, id: int) -> dict:
370
"""
371
Alias for account_unpin().
372
373
Args:
374
id: Account ID to remove endorsement from
375
376
Returns:
377
Relationship dictionary with updated status
378
"""
379
380
def account_note_set(self, id: int, comment: str) -> dict:
381
"""
382
Set a private note on an account (visible only to you).
383
384
Args:
385
id: Account ID
386
comment: Private note text
387
388
Returns:
389
Relationship dictionary with note information
390
"""
391
```
392
393
### Account Discovery
394
395
Search for accounts and get featured hashtags associated with user profiles.
396
397
```python { .api }
398
def account_search(
399
self,
400
q: str,
401
limit: int = 40,
402
following: bool = False,
403
resolve: bool = False
404
) -> list:
405
"""
406
Search for accounts by username or display name.
407
408
Args:
409
q: Search query
410
limit: Maximum number of results (default 40, max 80)
411
following: Only search among accounts you follow
412
resolve: Attempt to resolve non-local accounts
413
414
Returns:
415
List of matching account dictionaries
416
"""
417
418
def account_featured_tags(self, id: int) -> list:
419
"""
420
Get featured hashtags for an account.
421
422
Args:
423
id: Account ID
424
425
Returns:
426
List of featured hashtag dictionaries
427
"""
428
```
429
430
### Account Creation
431
432
Create new accounts programmatically (requires appropriate permissions).
433
434
```python { .api }
435
def create_account(
436
self,
437
username: str,
438
password: str,
439
email: str,
440
agreement: bool,
441
locale: str = "en",
442
reason: str = None,
443
fields: list = None,
444
invitation_code: str = None
445
) -> dict:
446
"""
447
Create a new user account.
448
449
Args:
450
username: Desired username
451
password: Account password
452
email: Email address
453
agreement: User agrees to terms of service
454
locale: User's preferred locale
455
reason: Reason for account creation (if required)
456
fields: Initial profile fields
457
invitation_code: Invitation code (if required)
458
459
Returns:
460
Dictionary containing account creation result and token
461
"""
462
463
def email_resend_confirmation(self) -> dict:
464
"""
465
Resend email confirmation for the authenticated account.
466
467
Returns:
468
Empty dictionary on success
469
"""
470
```
471
472
## Usage Examples
473
474
### Basic Account Operations
475
476
```python
477
from mastodon import Mastodon
478
479
mastodon = Mastodon(
480
access_token='your_token',
481
api_base_url='https://mastodon.social'
482
)
483
484
# Get your own account info
485
me = mastodon.account_verify_credentials()
486
print(f"Logged in as {me['acct']} with {me['followers_count']} followers")
487
488
# Look up and follow another account
489
account = mastodon.account_lookup("gargron@mastodon.social")
490
relationship = mastodon.account_follow(account['id'])
491
print(f"Now following {account['acct']}: {relationship['following']}")
492
493
# Get their recent posts
494
statuses = mastodon.account_statuses(account['id'], limit=5)
495
for status in statuses:
496
print(f"- {status['content'][:50]}...")
497
```
498
499
### Profile Management
500
501
```python
502
# Update your profile
503
updated_account = mastodon.account_update_credentials(
504
display_name="My New Display Name",
505
note="This is my updated bio with #hashtags",
506
fields_attributes=[
507
{"name": "Website", "value": "https://example.com"},
508
{"name": "Pronouns", "value": "they/them"}
509
],
510
bot=False,
511
discoverable=True
512
)
513
514
# Upload a new avatar
515
with open('avatar.jpg', 'rb') as avatar_file:
516
mastodon.account_update_credentials(
517
avatar=avatar_file,
518
avatar_mime_type='image/jpeg'
519
)
520
```
521
522
### Relationship Management
523
524
```python
525
# Get your followers and following
526
followers = mastodon.account_followers(me['id'])
527
following = mastodon.account_following(me['id'])
528
529
print(f"You have {len(followers)} followers and follow {len(following)} accounts")
530
531
# Check relationship status with multiple accounts
532
account_ids = [followers[0]['id'], following[0]['id']]
533
relationships = mastodon.account_relationships(account_ids)
534
535
for rel in relationships:
536
print(f"Account {rel['id']}: following={rel['following']}, followed_by={rel['followed_by']}")
537
538
# Mute an account temporarily (24 hours)
539
mastodon.account_mute(account_ids[0], duration=86400)
540
```
541
542
### Account Discovery
543
544
```python
545
# Search for accounts
546
search_results = mastodon.account_search("python", limit=10)
547
for account in search_results:
548
print(f"{account['acct']}: {account['display_name']}")
549
550
# Get familiar followers (mutual connections)
551
familiar = mastodon.account_familiar_followers([account['id'] for account in search_results[:3]])
552
for item in familiar:
553
print(f"Mutual followers with {item['id']}: {len(item['accounts'])}")
554
```
555
556
## Types
557
558
```python { .api }
559
# Account object structure
560
Account = {
561
'id': str, # Account ID
562
'username': str, # Username without domain
563
'acct': str, # Full account name (username@domain)
564
'display_name': str, # Display name
565
'locked': bool, # Requires follow approval
566
'bot': bool, # Is bot account
567
'discoverable': bool, # Appears in directory
568
'group': bool, # Is group account
569
'created_at': str, # Account creation date
570
'note': str, # Profile bio (HTML)
571
'url': str, # Profile URL
572
'avatar': str, # Avatar image URL
573
'avatar_static': str, # Static avatar URL
574
'header': str, # Header image URL
575
'header_static': str, # Static header URL
576
'followers_count': int, # Number of followers
577
'following_count': int, # Number of following
578
'statuses_count': int, # Number of statuses
579
'last_status_at': str, # Date of last status
580
'fields': list, # Profile fields
581
'emojis': list, # Custom emojis used
582
}
583
584
# Relationship object structure
585
Relationship = {
586
'id': str, # Account ID
587
'following': bool, # You follow this account
588
'followed_by': bool, # This account follows you
589
'blocking': bool, # You block this account
590
'blocked_by': bool, # This account blocks you
591
'muting': bool, # You mute this account
592
'muting_notifications': bool, # You mute notifications
593
'requested': bool, # Follow request pending
594
'domain_blocking': bool, # You block their domain
595
'showing_reblogs': bool, # You see their reblogs
596
'endorsed': bool, # You endorse this account
597
'notifying': bool, # You get notifications
598
'note': str, # Your private note
599
}
600
```