or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

Files

docs

async-interface.mdauthentication.mdclient-v2.mddata-models.mdindex.mdlegacy-api.mdstreaming.mdutilities.md

client-v2.mddocs/

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.*