0
# Twitter API v2 Client
1
2
The Client class provides comprehensive access to Twitter API v2 endpoints with support for both app-only and user authentication contexts. It handles tweet management, user operations, timelines, search, lists, spaces, direct messages, and media uploads.
3
4
## Capabilities
5
6
### Client Initialization
7
8
Create a Client instance with authentication credentials and configuration options.
9
10
```python { .api }
11
class Client:
12
def __init__(self, bearer_token=None, consumer_key=None, consumer_secret=None,
13
access_token=None, access_token_secret=None, *,
14
return_type=Response, wait_on_rate_limit=False):
15
"""
16
Initialize Twitter API v2 Client.
17
18
Parameters:
19
- bearer_token (str, optional): Bearer token for app-only authentication
20
- consumer_key (str, optional): Consumer key for user authentication
21
- consumer_secret (str, optional): Consumer secret for user authentication
22
- access_token (str, optional): Access token for user authentication
23
- access_token_secret (str, optional): Access token secret for user authentication
24
- return_type (type): Response container type (default: Response namedtuple)
25
- wait_on_rate_limit (bool): Wait when rate limit hit (default: False)
26
"""
27
```
28
29
### Tweet Management
30
31
Create, delete, and manage tweets with support for media attachments, polls, and reply settings.
32
33
```python { .api }
34
def create_tweet(self, text=None, *, direct_message_deep_link=None,
35
for_super_followers_only=None, geo=None, media_ids=None,
36
place_id=None, poll_options=None, poll_duration_minutes=None,
37
quote_tweet_id=None, reply=None, reply_settings=None,
38
super_followers_only=None, user_auth=True):
39
"""
40
Create a new tweet.
41
42
Parameters:
43
- text (str, optional): Tweet text content (required unless media_ids provided)
44
- media_ids (list, optional): List of media IDs to attach
45
- poll_options (list, optional): Poll options (2-4 strings)
46
- poll_duration_minutes (int, optional): Poll duration (5-10080 minutes)
47
- reply (dict, optional): Reply configuration {"in_reply_to_tweet_id": "id"}
48
- quote_tweet_id (str, optional): ID of tweet to quote
49
- geo (dict, optional): Geographic information
50
- reply_settings (str, optional): "everyone", "mentionedUsers", "following"
51
- user_auth (bool): Requires user authentication (default: True)
52
53
Returns:
54
Response with created tweet data
55
"""
56
57
def delete_tweet(self, id, *, user_auth=True):
58
"""
59
Delete a tweet by ID.
60
61
Parameters:
62
- id (str): Tweet ID to delete
63
- user_auth (bool): Requires user authentication (default: True)
64
65
Returns:
66
Response with deletion confirmation
67
"""
68
```
69
70
### Tweet Interactions
71
72
Like, retweet, bookmark, and manage tweet interactions.
73
74
```python { .api }
75
def like(self, tweet_id, *, user_auth=True):
76
"""
77
Like a tweet.
78
79
Parameters:
80
- tweet_id (str): ID of tweet to like
81
- user_auth (bool): Requires user authentication (default: True)
82
83
Returns:
84
Response with like status
85
"""
86
87
def unlike(self, tweet_id, *, user_auth=True):
88
"""
89
Remove like from a tweet.
90
91
Parameters:
92
- tweet_id (str): ID of tweet to unlike
93
- user_auth (bool): Requires user authentication (default: True)
94
95
Returns:
96
Response with unlike status
97
"""
98
99
def retweet(self, tweet_id, *, user_auth=True):
100
"""
101
Retweet a tweet.
102
103
Parameters:
104
- tweet_id (str): ID of tweet to retweet
105
- user_auth (bool): Requires user authentication (default: True)
106
107
Returns:
108
Response with retweet status
109
"""
110
111
def unretweet(self, source_tweet_id, *, user_auth=True):
112
"""
113
Remove a retweet.
114
115
Parameters:
116
- source_tweet_id (str): ID of original tweet that was retweeted
117
- user_auth (bool): Requires user authentication (default: True)
118
119
Returns:
120
Response with unretweet status
121
"""
122
123
def bookmark(self, tweet_id, *, user_auth=True):
124
"""
125
Add tweet to bookmarks.
126
127
Parameters:
128
- tweet_id (str): ID of tweet to bookmark
129
- user_auth (bool): Requires user authentication (default: True)
130
131
Returns:
132
Response with bookmark status
133
"""
134
135
def remove_bookmark(self, tweet_id, *, user_auth=True):
136
"""
137
Remove tweet from bookmarks.
138
139
Parameters:
140
- tweet_id (str): ID of tweet to remove from bookmarks
141
- user_auth (bool): Requires user authentication (default: True)
142
143
Returns:
144
Response with removal status
145
"""
146
```
147
148
### Tweet Lookup and Search
149
150
Retrieve tweets by ID, search recent and historical tweets, and get tweet quotes.
151
152
```python { .api }
153
def get_tweet(self, id, *, expansions=None, media_fields=None, place_fields=None,
154
poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False):
155
"""
156
Get a single tweet by ID.
157
158
Parameters:
159
- id (str): Tweet ID
160
- expansions (list, optional): Additional data to include
161
- tweet_fields (list, optional): Tweet fields to include
162
- user_fields (list, optional): User fields to include for authors
163
- media_fields (list, optional): Media fields to include
164
- poll_fields (list, optional): Poll fields to include
165
- place_fields (list, optional): Place fields to include
166
- user_auth (bool): Use user authentication (default: False)
167
168
Returns:
169
Response with tweet data
170
"""
171
172
def get_tweets(self, ids, *, expansions=None, media_fields=None, place_fields=None,
173
poll_fields=None, tweet_fields=None, user_fields=None, user_auth=False):
174
"""
175
Get multiple tweets by IDs.
176
177
Parameters:
178
- ids (list): List of tweet IDs (up to 100)
179
- expansions (list, optional): Additional data to include
180
- tweet_fields (list, optional): Tweet fields to include
181
- user_fields (list, optional): User fields to include
182
- media_fields (list, optional): Media fields to include
183
- poll_fields (list, optional): Poll fields to include
184
- place_fields (list, optional): Place fields to include
185
- user_auth (bool): Use user authentication (default: False)
186
187
Returns:
188
Response with tweets data
189
"""
190
191
def search_recent_tweets(self, query, *, end_time=None, expansions=None,
192
max_results=None, media_fields=None, next_token=None,
193
place_fields=None, poll_fields=None, since_id=None,
194
sort_order=None, start_time=None, tweet_fields=None,
195
until_id=None, user_fields=None, user_auth=False):
196
"""
197
Search for tweets from the last 7 days.
198
199
Parameters:
200
- query (str): Search query string
201
- max_results (int, optional): Number of results to return (10-100, default: 10)
202
- next_token (str, optional): Pagination token
203
- since_id (str, optional): Return results after this tweet ID
204
- until_id (str, optional): Return results before this tweet ID
205
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
206
- end_time (str, optional): Latest tweet creation time (ISO 8601)
207
- sort_order (str, optional): "recency" or "relevancy"
208
- expansions (list, optional): Additional data to include
209
- tweet_fields (list, optional): Tweet fields to include
210
- user_fields (list, optional): User fields to include
211
- media_fields (list, optional): Media fields to include
212
- poll_fields (list, optional): Poll fields to include
213
- place_fields (list, optional): Place fields to include
214
- user_auth (bool): Use user authentication (default: False)
215
216
Returns:
217
Response with search results and metadata
218
"""
219
220
def search_all_tweets(self, query, *, end_time=None, expansions=None,
221
max_results=None, media_fields=None, next_token=None,
222
place_fields=None, poll_fields=None, since_id=None,
223
sort_order=None, start_time=None, tweet_fields=None,
224
until_id=None, user_fields=None, user_auth=False):
225
"""
226
Search the complete archive of public tweets (Academic Research access required).
227
228
Parameters: Same as search_recent_tweets
229
230
Returns:
231
Response with search results and metadata
232
"""
233
234
def get_quote_tweets(self, id, *, expansions=None, exclude=None, max_results=None,
235
pagination_token=None, tweet_fields=None, user_fields=None,
236
user_auth=False):
237
"""
238
Get quotes of a specific tweet.
239
240
Parameters:
241
- id (str): Tweet ID to get quotes for
242
- max_results (int, optional): Number of results (10-100, default: 10)
243
- pagination_token (str, optional): Pagination token
244
- exclude (list, optional): Types to exclude ("retweets", "replies")
245
- expansions (list, optional): Additional data to include
246
- tweet_fields (list, optional): Tweet fields to include
247
- user_fields (list, optional): User fields to include
248
- user_auth (bool): Use user authentication (default: False)
249
250
Returns:
251
Response with quote tweets
252
"""
253
```
254
255
### Tweet Analytics
256
257
Get engagement metrics and analytics for tweets and users.
258
259
```python { .api }
260
def get_liked_tweets(self, id, *, expansions=None, max_results=None,
261
pagination_token=None, tweet_fields=None, user_fields=None,
262
user_auth=True):
263
"""
264
Get tweets liked by a user.
265
266
Parameters:
267
- id (str): User ID
268
- max_results (int, optional): Number of results (5-100, default: 100)
269
- pagination_token (str, optional): Pagination token
270
- expansions (list, optional): Additional data to include
271
- tweet_fields (list, optional): Tweet fields to include
272
- user_fields (list, optional): User fields to include
273
- user_auth (bool): Requires user authentication (default: True)
274
275
Returns:
276
Response with liked tweets
277
"""
278
279
def get_liking_users(self, id, *, expansions=None, max_results=None,
280
pagination_token=None, tweet_fields=None, user_fields=None,
281
user_auth=False):
282
"""
283
Get users who liked a specific tweet.
284
285
Parameters:
286
- id (str): Tweet ID
287
- max_results (int, optional): Number of results (1-100, default: 100)
288
- pagination_token (str, optional): Pagination token
289
- expansions (list, optional): Additional data to include
290
- tweet_fields (list, optional): Tweet fields to include
291
- user_fields (list, optional): User fields to include
292
- user_auth (bool): Use user authentication (default: False)
293
294
Returns:
295
Response with users who liked the tweet
296
"""
297
298
def get_retweeters(self, id, *, expansions=None, max_results=None,
299
pagination_token=None, tweet_fields=None, user_fields=None,
300
user_auth=False):
301
"""
302
Get users who retweeted a specific tweet.
303
304
Parameters:
305
- id (str): Tweet ID
306
- max_results (int, optional): Number of results (1-100, default: 100)
307
- pagination_token (str, optional): Pagination token
308
- expansions (list, optional): Additional data to include
309
- tweet_fields (list, optional): Tweet fields to include
310
- user_fields (list, optional): User fields to include
311
- user_auth (bool): Use user authentication (default: False)
312
313
Returns:
314
Response with users who retweeted the tweet
315
"""
316
317
def get_recent_tweets_count(self, query, *, end_time=None, granularity=None,
318
since_id=None, start_time=None, until_id=None,
319
user_auth=False):
320
"""
321
Count tweets from the recent search index (last 7 days).
322
323
Parameters:
324
- query (str): Search query string
325
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
326
- end_time (str, optional): Latest tweet creation time (ISO 8601)
327
- since_id (str, optional): Count results after this tweet ID
328
- until_id (str, optional): Count results before this tweet ID
329
- granularity (str, optional): "minute", "hour", or "day"
330
- user_auth (bool): Use user authentication (default: False)
331
332
Returns:
333
Response with tweet counts and time series data
334
"""
335
336
def get_all_tweets_count(self, query, *, end_time=None, granularity=None,
337
next_token=None, since_id=None, start_time=None,
338
until_id=None, user_auth=False):
339
"""
340
Count tweets from the full archive (Academic Research access required).
341
342
Parameters: Same as get_recent_tweets_count, plus:
343
- next_token (str, optional): Pagination token for large date ranges
344
345
Returns:
346
Response with tweet counts and time series data
347
"""
348
```
349
350
### Timelines
351
352
Access user timelines and tweet feeds.
353
354
```python { .api }
355
def get_home_timeline(self, *, end_time=None, exclude=None, expansions=None,
356
max_results=None, pagination_token=None, since_id=None,
357
start_time=None, tweet_fields=None, until_id=None,
358
user_fields=None, user_auth=True):
359
"""
360
Get the authenticated user's home timeline.
361
362
Parameters:
363
- max_results (int, optional): Number of results (5-100, default: 100)
364
- pagination_token (str, optional): Pagination token
365
- exclude (list, optional): Types to exclude ("retweets", "replies")
366
- since_id (str, optional): Return results after this tweet ID
367
- until_id (str, optional): Return results before this tweet ID
368
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
369
- end_time (str, optional): Latest tweet creation time (ISO 8601)
370
- expansions (list, optional): Additional data to include
371
- tweet_fields (list, optional): Tweet fields to include
372
- user_fields (list, optional): User fields to include
373
- user_auth (bool): Requires user authentication (default: True)
374
375
Returns:
376
Response with timeline tweets
377
"""
378
379
def get_users_tweets(self, id, *, end_time=None, exclude=None, expansions=None,
380
max_results=None, pagination_token=None, since_id=None,
381
start_time=None, tweet_fields=None, until_id=None,
382
user_fields=None, user_auth=False):
383
"""
384
Get tweets posted by a specific user.
385
386
Parameters:
387
- id (str): User ID
388
- max_results (int, optional): Number of results (5-100, default: 10)
389
- pagination_token (str, optional): Pagination token
390
- exclude (list, optional): Types to exclude ("retweets", "replies")
391
- since_id (str, optional): Return results after this tweet ID
392
- until_id (str, optional): Return results before this tweet ID
393
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
394
- end_time (str, optional): Latest tweet creation time (ISO 8601)
395
- expansions (list, optional): Additional data to include
396
- tweet_fields (list, optional): Tweet fields to include
397
- user_fields (list, optional): User fields to include
398
- user_auth (bool): Use user authentication (default: False)
399
400
Returns:
401
Response with user's tweets
402
"""
403
404
def get_users_mentions(self, id, *, end_time=None, expansions=None, max_results=None,
405
pagination_token=None, since_id=None, start_time=None,
406
tweet_fields=None, until_id=None, user_fields=None,
407
user_auth=True):
408
"""
409
Get tweets that mention a specific user.
410
411
Parameters:
412
- id (str): User ID
413
- max_results (int, optional): Number of results (5-100, default: 100)
414
- pagination_token (str, optional): Pagination token
415
- since_id (str, optional): Return results after this tweet ID
416
- until_id (str, optional): Return results before this tweet ID
417
- start_time (str, optional): Earliest tweet creation time (ISO 8601)
418
- end_time (str, optional): Latest tweet creation time (ISO 8601)
419
- expansions (list, optional): Additional data to include
420
- tweet_fields (list, optional): Tweet fields to include
421
- user_fields (list, optional): User fields to include
422
- user_auth (bool): Requires user authentication (default: True)
423
424
Returns:
425
Response with mention tweets
426
"""
427
```
428
429
### Reply Management
430
431
Hide and unhide replies to tweets.
432
433
```python { .api }
434
def hide_reply(self, id, *, user_auth=True):
435
"""
436
Hide a reply to a tweet.
437
438
Parameters:
439
- id (str): Tweet ID of the reply to hide
440
- user_auth (bool): Requires user authentication (default: True)
441
442
Returns:
443
Response with hide status
444
"""
445
446
def unhide_reply(self, id, *, user_auth=True):
447
"""
448
Unhide a previously hidden reply.
449
450
Parameters:
451
- id (str): Tweet ID of the reply to unhide
452
- user_auth (bool): Requires user authentication (default: True)
453
454
Returns:
455
Response with unhide status
456
"""
457
```
458
459
### User Management
460
461
Get user information and manage the authenticated user's profile.
462
463
```python { .api }
464
def get_me(self, *, expansions=None, tweet_fields=None, user_fields=None,
465
user_auth=True):
466
"""
467
Get the authenticated user's information.
468
469
Parameters:
470
- expansions (list, optional): Additional data to include
471
- tweet_fields (list, optional): Tweet fields for pinned tweet
472
- user_fields (list, optional): User fields to include
473
- user_auth (bool): Requires user authentication (default: True)
474
475
Returns:
476
Response with authenticated user's data
477
"""
478
479
def get_user(self, *, id=None, username=None, expansions=None, tweet_fields=None,
480
user_fields=None, user_auth=False):
481
"""
482
Get a user by ID or username.
483
484
Parameters:
485
- id (str, optional): User ID (required if username not provided)
486
- username (str, optional): Username handle (required if id not provided)
487
- expansions (list, optional): Additional data to include
488
- tweet_fields (list, optional): Tweet fields for pinned tweet
489
- user_fields (list, optional): User fields to include
490
- user_auth (bool): Use user authentication (default: False)
491
492
Returns:
493
Response with user data
494
"""
495
496
def get_users(self, *, ids=None, usernames=None, expansions=None, tweet_fields=None,
497
user_fields=None, user_auth=False):
498
"""
499
Get multiple users by IDs or usernames.
500
501
Parameters:
502
- ids (list, optional): List of user IDs (up to 100)
503
- usernames (list, optional): List of usernames (up to 100)
504
- expansions (list, optional): Additional data to include
505
- tweet_fields (list, optional): Tweet fields for pinned tweets
506
- user_fields (list, optional): User fields to include
507
- user_auth (bool): Use user authentication (default: False)
508
509
Returns:
510
Response with users data
511
"""
512
```
513
514
### User Relationships
515
516
Follow, unfollow, block, mute, and manage user relationships.
517
518
```python { .api }
519
def follow_user(self, target_user_id, *, user_auth=True):
520
"""
521
Follow a user.
522
523
Parameters:
524
- target_user_id (str): ID of user to follow
525
- user_auth (bool): Requires user authentication (default: True)
526
527
Returns:
528
Response with follow status
529
"""
530
531
def unfollow_user(self, target_user_id, *, user_auth=True):
532
"""
533
Unfollow a user.
534
535
Parameters:
536
- target_user_id (str): ID of user to unfollow
537
- user_auth (bool): Requires user authentication (default: True)
538
539
Returns:
540
Response with unfollow status
541
"""
542
543
def follow(self, target_user_id, *, user_auth=True):
544
"""
545
Follow a user (alias for follow_user).
546
547
Parameters:
548
- target_user_id (str): ID of user to follow
549
- user_auth (bool): Requires user authentication (default: True)
550
551
Returns:
552
Response with follow status
553
"""
554
555
def unfollow(self, target_user_id, *, user_auth=True):
556
"""
557
Unfollow a user (alias for unfollow_user).
558
559
Parameters:
560
- target_user_id (str): ID of user to unfollow
561
- user_auth (bool): Requires user authentication (default: True)
562
563
Returns:
564
Response with unfollow status
565
"""
566
567
def get_users_followers(self, id, *, expansions=None, max_results=None,
568
pagination_token=None, tweet_fields=None, user_fields=None,
569
user_auth=False):
570
"""
571
Get a user's followers.
572
573
Parameters:
574
- id (str): User ID
575
- max_results (int, optional): Number of results (1-1000, default: 100)
576
- pagination_token (str, optional): Pagination token
577
- expansions (list, optional): Additional data to include
578
- tweet_fields (list, optional): Tweet fields for pinned tweets
579
- user_fields (list, optional): User fields to include
580
- user_auth (bool): Use user authentication (default: False)
581
582
Returns:
583
Response with followers data
584
"""
585
586
def get_users_following(self, id, *, expansions=None, max_results=None,
587
pagination_token=None, tweet_fields=None, user_fields=None,
588
user_auth=False):
589
"""
590
Get users that a user is following.
591
592
Parameters:
593
- id (str): User ID
594
- max_results (int, optional): Number of results (1-1000, default: 100)
595
- pagination_token (str, optional): Pagination token
596
- expansions (list, optional): Additional data to include
597
- tweet_fields (list, optional): Tweet fields for pinned tweets
598
- user_fields (list, optional): User fields to include
599
- user_auth (bool): Use user authentication (default: False)
600
601
Returns:
602
Response with following data
603
"""
604
605
def block(self, target_user_id, *, user_auth=True):
606
"""
607
Block a user.
608
609
Parameters:
610
- target_user_id (str): ID of user to block
611
- user_auth (bool): Requires user authentication (default: True)
612
613
Returns:
614
Response with block status
615
"""
616
617
def unblock(self, target_user_id, *, user_auth=True):
618
"""
619
Unblock a user.
620
621
Parameters:
622
- target_user_id (str): ID of user to unblock
623
- user_auth (bool): Requires user authentication (default: True)
624
625
Returns:
626
Response with unblock status
627
"""
628
629
def get_blocked(self, *, expansions=None, max_results=None, pagination_token=None,
630
tweet_fields=None, user_fields=None, user_auth=True):
631
"""
632
Get the authenticated user's blocked users.
633
634
Parameters:
635
- max_results (int, optional): Number of results (1-1000, default: 100)
636
- pagination_token (str, optional): Pagination token
637
- expansions (list, optional): Additional data to include
638
- tweet_fields (list, optional): Tweet fields for pinned tweets
639
- user_fields (list, optional): User fields to include
640
- user_auth (bool): Requires user authentication (default: True)
641
642
Returns:
643
Response with blocked users data
644
"""
645
646
def mute(self, target_user_id, *, user_auth=True):
647
"""
648
Mute a user.
649
650
Parameters:
651
- target_user_id (str): ID of user to mute
652
- user_auth (bool): Requires user authentication (default: True)
653
654
Returns:
655
Response with mute status
656
"""
657
658
def unmute(self, target_user_id, *, user_auth=True):
659
"""
660
Unmute a user.
661
662
Parameters:
663
- target_user_id (str): ID of user to unmute
664
- user_auth (bool): Requires user authentication (default: True)
665
666
Returns:
667
Response with unmute status
668
"""
669
670
def get_muted(self, *, expansions=None, max_results=None, pagination_token=None,
671
tweet_fields=None, user_fields=None, user_auth=True):
672
"""
673
Get the authenticated user's muted users.
674
675
Parameters:
676
- max_results (int, optional): Number of results (1-1000, default: 100)
677
- pagination_token (str, optional): Pagination token
678
- expansions (list, optional): Additional data to include
679
- tweet_fields (list, optional): Tweet fields for pinned tweets
680
- user_fields (list, optional): User fields to include
681
- user_auth (bool): Requires user authentication (default: True)
682
683
Returns:
684
Response with muted users data
685
"""
686
```
687
688
### Bookmarks
689
690
Manage the authenticated user's bookmarks.
691
692
```python { .api }
693
def get_bookmarks(self, *, expansions=None, max_results=None, pagination_token=None,
694
tweet_fields=None, user_fields=None, user_auth=True):
695
"""
696
Get the authenticated user's bookmarks.
697
698
Parameters:
699
- max_results (int, optional): Number of results (1-100, default: 100)
700
- pagination_token (str, optional): Pagination token
701
- expansions (list, optional): Additional data to include
702
- tweet_fields (list, optional): Tweet fields to include
703
- user_fields (list, optional): User fields to include
704
- user_auth (bool): Requires user authentication (default: True)
705
706
Returns:
707
Response with bookmarked tweets
708
"""
709
```
710
711
*Note: This document continues with additional Client methods for Lists, Spaces, Direct Messages, Compliance, and Media Upload. The complete Client class contains over 80 methods covering all Twitter API v2 endpoints.*