0
# Status Operations
1

2
Creating, editing, and managing posts (statuses/toots) on Mastodon including media attachments, polls, scheduling, and all status-related actions like favoriting, boosting, and bookmarking.
3

4
## Capabilities
5

6
### Status Creation
7

8
Create new posts with various content types, media attachments, and configuration options.
9

10
```python { .api }
11
def status_post(
12
    self,
13
    status: str,
14
    in_reply_to_id: int = None,
15
    media_ids: list = None,
16
    sensitive: bool = False,
17
    visibility: str = None,
18
    spoiler_text: str = None,
19
    language: str = None,
20
    idempotency_key: str = None,
21
    content_type: str = None,
22
    scheduled_at: datetime = None,
23
    poll: dict = None,
24
    quote_id: int = None
25
) -> dict:
26
    """
27
    Create a new status (post/toot).
28
    
29
    Args:
30
        status: Status text content (required)
31
        in_reply_to_id: ID of status to reply to
32
        media_ids: List of media attachment IDs
33
        sensitive: Mark as sensitive content
34
        visibility: Visibility level ('public', 'unlisted', 'private', 'direct')
35
        spoiler_text: Content warning/spoiler text
36
        language: ISO 639-1 language code
37
        idempotency_key: Unique key to prevent duplicate posts
38
        content_type: Content type ('text/plain', 'text/markdown', 'text/html')
39
        scheduled_at: Schedule post for future publication
40
        poll: Poll configuration dictionary
41
        quote_id: ID of status to quote (instance-dependent)
42
    
43
    Returns:
44
        Dictionary containing created status information
45
    """
46

47
def toot(self, status: str) -> dict:
48
    """
49
    Alias for status_post() - not recommended, use status_post() instead.
50
    
51
    Args:
52
        status: Status text content
53
    
54
    Returns:
55
        Dictionary containing created status information
56
    """
57

58
def status_reply(
59
    self,
60
    to_status: dict,
61
    status: str,
62
    media_ids: list = None,
63
    sensitive: bool = False,
64
    visibility: str = None,
65
    spoiler_text: str = None,
66
    language: str = None,
67
    idempotency_key: str = None,
68
    content_type: str = None,
69
    scheduled_at: datetime = None,
70
    poll: dict = None,
71
    untag: bool = False
72
) -> dict:
73
    """
74
    Reply to an existing status with automatic mention handling.
75
    
76
    Args:
77
        to_status: Status dictionary to reply to
78
        status: Reply text content
79
        media_ids: List of media attachment IDs
80
        sensitive: Mark as sensitive content
81
        visibility: Visibility level (defaults to original status visibility)
82
        spoiler_text: Content warning/spoiler text
83
        language: ISO 639-1 language code
84
        idempotency_key: Unique key to prevent duplicate posts
85
        content_type: Content type
86
        scheduled_at: Schedule reply for future publication
87
        poll: Poll configuration dictionary
88
        untag: Remove automatic mentions from reply
89
    
90
    Returns:
91
        Dictionary containing created reply status
92
    """
93
```
94

95
### Status Editing
96

97
Edit existing posts and view edit history (Mastodon 3.5.0+).
98

99
```python { .api }
100
def status_update(
101
    self,
102
    id: int,
103
    status: str = None,
104
    spoiler_text: str = None,
105
    sensitive: bool = None,
106
    media_ids: list = None,
107
    poll: dict = None,
108
    language: str = None
109
) -> dict:
110
    """
111
    Edit an existing status (Mastodon 3.5.0+).
112
    
113
    Args:
114
        id: Status ID to edit
115
        status: New status text content
116
        spoiler_text: New content warning/spoiler text
117
        sensitive: New sensitive content flag
118
        media_ids: New list of media attachment IDs
119
        poll: New poll configuration
120
        language: New ISO 639-1 language code
121
    
122
    Returns:
123
        Dictionary containing updated status information
124
    """
125

126
def status_history(self, id: int) -> list:
127
    """
128
    Get edit history for a status (Mastodon 3.5.0+).
129
    
130
    Args:
131
        id: Status ID
132
    
133
    Returns:
134
        List of status edit history entries
135
    """
136

137
def status_source(self, id: int) -> dict:
138
    """
139
    Get the source text of a status for editing purposes.
140
    
141
    Args:
142
        id: Status ID
143
    
144
    Returns:
145
        Dictionary containing status source information
146
    """
147

148
def generate_media_edit_attributes(
149
    self,
150
    media_dict: dict,
151
    media_ids: list
152
) -> list:
153
    """
154
    Helper function to generate media edit attributes for status updates.
155
    
156
    Args:
157
        media_dict: Dictionary of media attachment updates
158
        media_ids: List of media IDs to update
159
    
160
    Returns:
161
        List of media edit attribute dictionaries
162
    """
163
```
164

165
### Status Information
166

167
Retrieve status details, context, and interaction information.
168

169
```python { .api }
170
def status(self, id: int) -> dict:
171
    """
172
    Get a single status by ID.
173
    
174
    Args:
175
        id: Status ID
176
    
177
    Returns:
178
        Dictionary containing status information
179
    """
180

181
def statuses(self, ids: list) -> list:
182
    """
183
    Get multiple statuses by IDs (Mastodon 4.3.0+).
184
    
185
    Args:
186
        ids: List of status IDs
187
    
188
    Returns:
189
        List of status dictionaries
190
    """
191

192
def status_context(self, id: int) -> dict:
193
    """
194
    Get the context (ancestors and descendants) of a status.
195
    
196
    Args:
197
        id: Status ID
198
    
199
    Returns:
200
        Dictionary with 'ancestors' and 'descendants' lists
201
    """
202

203
def status_card(self, id: int) -> dict:
204
    """
205
    Get the preview card for a status (deprecated - use status() instead).
206
    
207
    Args:
208
        id: Status ID
209
    
210
    Returns:
211
        Dictionary containing preview card information
212
    """
213

214
def status_reblogged_by(
215
    self,
216
    id: int,
217
    max_id: int = None,
218
    min_id: int = None,
219
    since_id: int = None,
220
    limit: int = 40
221
) -> list:
222
    """
223
    Get accounts that reblogged (boosted) a status.
224
    
225
    Args:
226
        id: Status ID
227
        max_id: Return results older than this ID
228
        min_id: Return results newer than this ID
229
        since_id: Return results newer than this ID
230
        limit: Maximum number of results (default 40, max 80)
231
    
232
    Returns:
233
        List of account dictionaries
234
    """
235

236
def status_favourited_by(
237
    self,
238
    id: int,
239
    max_id: int = None,
240
    min_id: int = None,
241
    since_id: int = None,
242
    limit: int = 40
243
) -> list:
244
    """
245
    Get accounts that favorited a status.
246
    
247
    Args:
248
        id: Status ID
249
        max_id: Return results older than this ID
250
        min_id: Return results newer than this ID
251
        since_id: Return results newer than this ID
252
        limit: Maximum number of results (default 40, max 80)
253
    
254
    Returns:
255
        List of account dictionaries
256
    """
257
```
258

259
### Status Actions
260

261
Perform actions on statuses including favoriting, boosting, bookmarking, and deletion.
262

263
```python { .api }
264
def status_favourite(self, id: int) -> dict:
265
    """
266
    Favorite (like) a status.
267
    
268
    Args:
269
        id: Status ID to favorite
270
    
271
    Returns:
272
        Dictionary containing updated status with favorited=True
273
    """
274

275
def status_unfavourite(self, id: int) -> dict:
276
    """
277
    Remove favorite from a status.
278
    
279
    Args:
280
        id: Status ID to unfavorite
281
    
282
    Returns:
283
        Dictionary containing updated status with favorited=False
284
    """
285

286
def status_reblog(self, id: int, visibility: str = None) -> dict:
287
    """
288
    Reblog (boost) a status.
289
    
290
    Args:
291
        id: Status ID to reblog
292
        visibility: Visibility of the reblog ('public', 'unlisted', 'private')
293
    
294
    Returns:
295
        Dictionary containing the reblog status
296
    """
297

298
def status_unreblog(self, id: int) -> dict:
299
    """
300
    Remove reblog from a status.
301
    
302
    Args:
303
        id: Status ID to unreblog
304
    
305
    Returns:
306
        Dictionary containing the original status with reblogged=False
307
    """
308

309
def status_bookmark(self, id: int) -> dict:
310
    """
311
    Bookmark a status for later reference.
312
    
313
    Args:
314
        id: Status ID to bookmark
315
    
316
    Returns:
317
        Dictionary containing updated status with bookmarked=True
318
    """
319

320
def status_unbookmark(self, id: int) -> dict:
321
    """
322
    Remove bookmark from a status.
323
    
324
    Args:
325
        id: Status ID to remove bookmark from
326
    
327
    Returns:
328
        Dictionary containing updated status with bookmarked=False
329
    """
330

331
def status_delete(self, id: int) -> dict:
332
    """
333
    Delete a status.
334
    
335
    Args:
336
        id: Status ID to delete (must be owned by authenticated user)
337
    
338
    Returns:
339
        Dictionary containing deleted status information
340
    """
341
```
342

343
### Status Management
344

345
Pin statuses to profile, mute conversations, and translate content.
346

347
```python { .api }
348
def status_pin(self, id: int) -> dict:
349
    """
350
    Pin a status to your profile.
351
    
352
    Args:
353
        id: Status ID to pin (must be owned by authenticated user)
354
    
355
    Returns:
356
        Dictionary containing updated status with pinned=True
357
    """
358

359
def status_unpin(self, id: int) -> dict:
360
    """
361
    Unpin a status from your profile.
362
    
363
    Args:
364
        id: Status ID to unpin
365
    
366
    Returns:
367
        Dictionary containing updated status with pinned=False
368
    """
369

370
def status_mute(self, id: int) -> dict:
371
    """
372
    Mute notifications from a conversation thread.
373
    
374
    Args:
375
        id: Status ID in conversation to mute
376
    
377
    Returns:
378
        Dictionary containing updated status with muted=True
379
    """
380

381
def status_unmute(self, id: int) -> dict:
382
    """
383
    Unmute notifications from a conversation thread.
384
    
385
    Args:
386
        id: Status ID in conversation to unmute
387
    
388
    Returns:
389
        Dictionary containing updated status with muted=False
390
    """
391

392
def status_translate(self, id: int, lang: str = None) -> dict:
393
    """
394
    Translate a status to another language (Mastodon 4.0.0+).
395
    
396
    Args:
397
        id: Status ID to translate
398
        lang: Target language code (auto-detected from user preferences if None)
399
    
400
    Returns:
401
        Dictionary containing translation information
402
    """
403
```
404

405
### Scheduled Statuses
406

407
Manage scheduled posts including viewing, updating, and deleting future posts.
408

409
```python { .api }
410
def scheduled_statuses(
411
    self,
412
    max_id: int = None,
413
    min_id: int = None,
414
    since_id: int = None,
415
    limit: int = 20
416
) -> list:
417
    """
418
    Get scheduled statuses for the authenticated user.
419
    
420
    Args:
421
        max_id: Return results older than this ID
422
        min_id: Return results newer than this ID
423
        since_id: Return results newer than this ID
424
        limit: Maximum number of results (default 20, max 40)
425
    
426
    Returns:
427
        List of scheduled status dictionaries
428
    """
429

430
def scheduled_status(self, id: int) -> dict:
431
    """
432
    Get a single scheduled status by ID.
433
    
434
    Args:
435
        id: Scheduled status ID
436
    
437
    Returns:
438
        Dictionary containing scheduled status information
439
    """
440

441
def scheduled_status_update(
442
    self,
443
    id: int,
444
    scheduled_at: datetime
445
) -> dict:
446
    """
447
    Update the scheduled time for a scheduled status.
448
    
449
    Args:
450
        id: Scheduled status ID
451
        scheduled_at: New scheduled publication time
452
    
453
    Returns:
454
        Dictionary containing updated scheduled status
455
    """
456

457
def scheduled_status_delete(self, id: int) -> dict:
458
    """
459
    Delete a scheduled status.
460
    
461
    Args:
462
        id: Scheduled status ID to delete
463
    
464
    Returns:
465
        Empty dictionary on success
466
    """
467
```
468

469
## Usage Examples
470

471
### Basic Status Creation
472

473
```python
474
from mastodon import Mastodon
475
from datetime import datetime, timedelta
476

477
mastodon = Mastodon(
478
    access_token='your_token',
479
    api_base_url='https://mastodon.social'
480
)
481

482
# Simple status post
483
status = mastodon.status_post("Hello, Mastodon! 👋")
484
print(f"Posted status: {status['url']}")
485

486
# Status with content warning and sensitive flag
487
sensitive_status = mastodon.status_post(
488
    "This is sensitive content behind a warning",
489
    spoiler_text="Content Warning: Sensitive Topic",
490
    sensitive=True,
491
    visibility="unlisted"
492
)
493

494
# Schedule a status for later
495
future_time = datetime.now() + timedelta(hours=2)
496
scheduled = mastodon.status_post(
497
    "This post will appear in 2 hours!",
498
    scheduled_at=future_time
499
)
500
print(f"Scheduled status ID: {scheduled['id']}")
501
```
502

503
### Status with Media and Poll
504

505
```python
506
# Upload media first
507
with open('image.jpg', 'rb') as image_file:
508
    media = mastodon.media_post(
509
        image_file,
510
        description="A beautiful sunset photo"
511
    )
512

513
# Create poll options
514
poll_options = {
515
    'options': ['Option 1', 'Option 2', 'Option 3'],
516
    'expires_in': 86400,  # 24 hours in seconds
517
    'multiple': False,    # Single choice
518
    'hide_totals': False  # Show vote counts
519
}
520

521
# Post status with media and poll
522
status = mastodon.status_post(
523
    "Check out this sunset! Also, what's your favorite time of day?",
524
    media_ids=[media['id']],
525
    poll=poll_options,
526
    sensitive=False
527
)
528
```
529

530
### Reply and Conversation Handling
531

532
```python
533
# Get a status to reply to
534
timeline = mastodon.timeline_home(limit=1)
535
original_status = timeline[0]
536

537
# Reply to the status
538
reply = mastodon.status_reply(
539
    original_status,
540
    "This is my reply to your post!",
541
    visibility="public"
542
)
543

544
# Get the full conversation context
545
context = mastodon.status_context(reply['id'])
546
print(f"Ancestors: {len(context['ancestors'])}")
547
print(f"Descendants: {len(context['descendants'])}")
548

549
# Mute the conversation to stop notifications
550
mastodon.status_mute(reply['id'])
551
```
552

553
### Status Actions and Interactions
554

555
```python
556
# Get a status
557
status_id = 123456789
558

559
# Perform various actions
560
mastodon.status_favourite(status_id)
561
mastodon.status_reblog(status_id, visibility="public")
562
mastodon.status_bookmark(status_id)
563

564
# Check who interacted with the status
565
favorites = mastodon.status_favourited_by(status_id, limit=10)
566
reblogs = mastodon.status_reblogged_by(status_id, limit=10)
567

568
print(f"Favorited by {len(favorites)} accounts")
569
print(f"Reblogged by {len(reblogs)} accounts")
570

571
# Pin to profile (if it's your status)
572
my_status = mastodon.status_post("This is my pinned post!")
573
mastodon.status_pin(my_status['id'])
574
```
575

576
### Status Editing
577

578
```python
579
# Create a status
580
original = mastodon.status_post("This is my original post with a typo.")
581

582
# Edit the status (Mastodon 3.5.0+)
583
edited = mastodon.status_update(
584
    original['id'],
585
    status="This is my original post with the typo fixed!",
586
    language="en"
587
)
588

589
# View edit history
590
history = mastodon.status_history(original['id'])
591
print(f"Status has been edited {len(history) - 1} times")
592

593
# Get source text for further editing
594
source = mastodon.status_source(original['id'])
595
print(f"Source text: {source['text']}")
596
```
597

598
### Scheduled Status Management
599

600
```python
601
from datetime import datetime, timedelta
602

603
# Create scheduled statuses
604
tomorrow = datetime.now() + timedelta(days=1)
605
next_week = datetime.now() + timedelta(weeks=1)
606

607
mastodon.status_post("Daily reminder!", scheduled_at=tomorrow)
608
mastodon.status_post("Weekly update!", scheduled_at=next_week)
609

610
# List all scheduled statuses
611
scheduled_list = mastodon.scheduled_statuses()
612
for scheduled in scheduled_list:
613
    print(f"'{scheduled['params']['text']}' scheduled for {scheduled['scheduled_at']}")
614

615
# Update scheduling time
616
if scheduled_list:
617
    new_time = datetime.now() + timedelta(hours=3)
618
    updated = mastodon.scheduled_status_update(
619
        scheduled_list[0]['id'],
620
        scheduled_at=new_time
621
    )
622
    print(f"Rescheduled to: {updated['scheduled_at']}")
623
```
624

625
## Types
626

627
```python { .api }
628
# Status object structure
629
Status = {
630
    'id': str,                    # Status ID
631
    'created_at': str,            # Creation timestamp
632
    'in_reply_to_id': str,        # ID of replied-to status
633
    'in_reply_to_account_id': str,# ID of replied-to account
634
    'sensitive': bool,            # Contains sensitive content
635
    'spoiler_text': str,          # Content warning text
636
    'visibility': str,            # Visibility level
637
    'language': str,              # Language code
638
    'uri': str,                   # ActivityPub URI
639
    'url': str,                   # Web URL
640
    'replies_count': int,         # Number of replies
641
    'reblogs_count': int,         # Number of reblogs
642
    'favourites_count': int,      # Number of favorites
643
    'edited_at': str,             # Last edit timestamp
644
    'favourited': bool,           # User has favorited
645
    'reblogged': bool,            # User has reblogged
646
    'muted': bool,                # User has muted thread
647
    'bookmarked': bool,           # User has bookmarked
648
    'pinned': bool,               # Pinned to user profile
649
    'content': str,               # HTML content
650
    'filtered': list,             # Applied filters
651
    'reblog': dict,               # Reblogged status (if reblog)
652
    'application': dict,          # Publishing application
653
    'account': dict,              # Author account
654
    'media_attachments': list,    # Media files
655
    'mentions': list,             # Account mentions
656
    'tags': list,                 # Hashtags
657
    'emojis': list,               # Custom emojis
658
    'card': dict,                 # Preview card
659
    'poll': dict,                 # Poll data
660
}
661

662
# Poll structure for status creation
663
Poll = {
664
    'options': list,              # List of option strings
665
    'expires_in': int,            # Expiration time in seconds
666
    'multiple': bool,             # Allow multiple choices
667
    'hide_totals': bool,          # Hide vote counts until closed
668
}
669

670
# Scheduled status structure
671
ScheduledStatus = {
672
    'id': str,                    # Scheduled status ID
673
    'scheduled_at': str,          # Publication timestamp
674
    'params': dict,               # Status parameters
675
    'media_attachments': list,    # Media attachments
676
}
677
```