API v2

September 4, 2025 · View on GitHub

This is a comprehensive guide of all methods available for the Twitter API v2 on twitter-api-v2 package.

Every presented method in this guide is attached to v2 client, that you can access through client.v2.

If you don't find the endpoint you want, don't panic! It probably hasn't been implemented yet. You can make your request manually using generic requests handlers .get, .post, .put, .patch and .delete methods. See the HTTP wrappers documentation.

Argument note: Described arguments often refers to an interface name. Generally, argument type is a Partial<> (all properties are optionals) of the given interface.

Return type note: All return types are wrapped inside Promises.

Twitter API v2 intensively uses includes to efficiently attach data to items (medias, polls, users, ...) fetched through the API. An includes helper is available here to help you browsing included metas in your response data.

For streaming API, see Streaming part.

Tweet timelines

Search tweets (recent)

Search tweets of the last 7 days with a text query. Get to know how paginators work here.

Method: .search()

Endpoint: tweets/search/recent

Right level: Read-only

Arguments:

  • query: string
  • options?: Tweetv2SearchParams

or

  • options?: Tweetv2SearchParams

Returns: TweetSearchRecentV2Paginator

Example

const jsTweets = await client.v2.search('JavaScript', { 'media.fields': 'url' });

// Consume every possible tweet of jsTweets (until rate limit is hit)
for await (const tweet of jsTweets) {
  console.log(tweet);
}

Search tweets (all)

Search tweets (from Twitter creation in 2006) with a text query. Get to know how paginators work here.

Method: .searchAll()

Endpoint: tweets/search/all

Right level: Read-only

Arguments:

  • query: string
  • options?: Tweetv2SearchParams

Returns: TweetSearchAllV2Paginator

Example

const jsTweets = await client.v2.searchAll('JavaScript', { 'media.fields': 'url' });

// Consume fetched tweet from first page of jsTweets
for (const tweet of jsTweets) {
  console.log(tweet);
}

Home timeline

Get reverse chronological tweet timeline of logged user. Get to know how paginators work here.

Method: .homeTimeline()

Endpoint: users/:id/timelines/reverse_chronological

Right level: Read-only

Arguments:

  • options?: TweetV2HomeTimelineParams

Returns: TweetHomeTimelineV2Paginator (containing TweetV2 entities)

Example

const homeTimeline = await client.v2.homeTimeline({ exclude: 'replies' });

User timeline

Get tweets of user userId. Get to know how paginators work here.

Method: .userTimeline()

Endpoint: users/:id/tweets

Right level: Read-only

Arguments:

  • userId: string
  • options?: TweetV2UserTimelineParams

Returns: TweetUserTimelineV2Paginator

Example

const tweetsOfJack = await client.v2.userTimeline('12', { exclude: 'replies' });

User mention timeline

Get mentions of user userId. Get to know how paginators work here.

Method: .userMentionTimeline()

Endpoint: users/:id/mentions

Right level: Read-only

Arguments:

  • userId: string
  • options?: TweetV2UserTimelineParams

Returns: TweetUserMentionTimelineV2Paginator

Example

const tweetsOfJack = await client.v2.userMentionTimeline('12', { end_time: '2020-01-01' });

Tweets

Create a tweet

Post a new tweet.

Method: .tweet()

Endpoint: tweets

Right level: Read-write

Arguments:

  • statusOrPayload: string | SendTweetV2Params
  • payload?: SendTweetV2Params

Returns: TweetV2PostTweetResult

Example

const { data: createdTweet } = await client.v2.tweet('twitter-api-v2 is awesome!', {
  poll: { duration_minutes: 120, options: ['Absolutely', 'For sure!'] },
});
console.log('Tweet', createdTweet.id, ':', createdTweet.text);

Reply to a tweet

Alias to .tweet() with reply: { in_reply_to_tweet_id: tweetId } already set.

Method: .reply()

Endpoint: tweets

Right level: Read-write

Arguments:

  • status: string – text of the reply.
  • tweetId: string – ID of the tweet you want to reply to (sets in_reply_to_tweet_id in the payload).
  • payload?: SendTweetV2Params – optional additional parameters (e.g., media, geolocation).

Returns: TweetV2PostTweetResult

Example

await client.v2.reply(
  'reply to previously created tweet.',
  createdTweet.id,
);

Quote a tweet

Quote an existing tweet with additional text.

Method: .quote()

Endpoint: tweets (POST)

Right level: Read-write

Arguments:

  • status: string – text of the quoting tweet.
  • quotedTweetId: string – ID of the tweet to quote.
  • payload?: SendTweetV2Params – optional additional parameters (e.g., media, geolocation).

Returns: TweetV2PostTweetResult

Example

// Quote tweet ID 1456789 with some text
const result = await client.v2.quote('Check this out!', '1456789');
console.log(result.data.id);

Post a thread of tweets

Post multiple tweets at one time.

Method: .tweetThread()

Endpoint: tweets

Right level: Read-write

Arguments:

  • tweets: (SendTweetV2Params | string)[]

Returns: TweetV2PostTweetResult[]: Created tweets results (in the right order), first sent first position

Example

// You can use media IDs generated by v1 API to send medias!
const mediaId = await client.v1.uploadMedia('./image.png');

await client.v2.tweetThread([
  'Hello, lets talk about Twitter!',
  { text: 'Twitter is a fantastic social network. Look at this:', media: { media_ids: [mediaId] } },
  'This thread is automatically made with twitter-api-v2 :D',
]);

Delete a tweet

Delete a tweet that belongs to you.

Method: .deleteTweet()

Endpoint: tweets/:id

Right level: Read-write

Arguments:

  • tweetId: string

Returns: TweetV2DeleteTweetResult

Example

await client.v2.deleteTweet('20');

Get a Single tweet

Method: .singleTweet()

Endpoint: tweets/:id

Right level: Read-only

Arguments:

  • tweetId: string
  • options?: Tweetv2FieldsParams

Returns: TweetV2SingleResult

Example

const tweetOfId20 = await client.v2.singleTweet('20', {
  expansions: [
    'entities.mentions.username',
    'in_reply_to_user_id',
  ],
});

Lookup for tweets

Get multiple tweets by ID.

Method: .tweets()

Endpoint: tweets

Right level: Read-only

Arguments:

  • tweetIds: string | string[]
  • options?: Tweetv2FieldsParams

Returns: TweetV2LookupResult

Example

const tweets = await client.v2.tweets(['20', '141']);

Get users that liked a specific tweet

Method: .tweetLikedBy()

Endpoint: tweets/:id/liking_users

Right level: Read-only

Arguments:

  • tweetId: string
  • options?: TweetRetweetedOrLikedByV2Params

Returns: TweetV2LikedByResult or TweetLikingUsersV2Paginator (if options.asPaginator)

Example

const users = await client.v2.tweetLikedBy('20');
console.log(users.data[0].id);

const usersPaginated = await client.v2.tweetLikedBy('20', { asPaginator: true });

for await (const user of usersPaginated) {
  console.log(user.id);
}

Like a tweet

Like a single tweet.

Method: .like()

Endpoint: users/:loggedUserId/likes (POST)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • tweetId: string: Tweet to like

Returns: TweetV2LikeResult

Example

await client.v2.like('12', '20');

Unlike a tweet

Remove a like of a single tweet.

Method: .unlike()

Endpoint: users/:loggedUserId/likes/:tweetId (DELETE)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • tweetId: string: Tweet to unlike

Returns: TweetV2LikeResult

Example

await client.v2.unlike('12', '20');

Hide/unhide a reply

Hide or unhide a specific reply to one of your tweets.

Method: .hideReply()

Endpoint: tweets/:id/hidden (PUT)

Right level: Read-write

Arguments:

  • tweetId: string – ID of the reply to hide or unhide.
  • makeHidden: boolean – true to hide, false to unhide.

Returns: TweetV2HideReplyResult

Example

// Hide a reply
await client.v2.hideReply('1234567890', true);
// Unhide the same reply
await client.v2.hideReply('1234567890', false);

Get tweet counts for a search (recent tweet only)

Method: .tweetCountRecent()

Endpoint: tweets/counts/recent

Right level: Read-only

Arguments:

  • query: string
  • options?: TweetV2CountParams

Returns: TweetV2CountResult

Example

const recentTweetsWithNode = await client.v2.tweetCountRecent('NodeJs');
console.log(recentTweetsWithNode.data[0].tweet_count);

Get tweet counts for a search (full archive)

Method: .tweetCountAll()

Endpoint: tweets/counts/all

Right level: Read-only

Arguments:

  • query: string
  • options?: TweetV2CountAllParams

Returns: TweetV2CountAllResult

Example

const allTweetsWithNode = await client.v2.tweetCountAll('NodeJs');
console.log(allTweetsWithNode.data[0].tweet_count);

Get users that retweeted a specific tweet

Method: .tweetRetweetedBy()

Endpoint: tweets/:id/retweeted_by

Right level: Read-only

Arguments:

  • tweetId: string
  • options?: TweetRetweetedOrLikedByV2Params

Returns: TweetV2RetweetedByResult or TweetRetweetersUsersV2Paginator (if options.asPaginator)

Example

const users = await client.v2.tweetRetweetedBy('20');
console.log(users.data[0].id);

const usersPaginated = await client.v2.tweetRetweetedBy('20', { asPaginator: true });

for await (const user of usersPaginated) {
  console.log(user.id);
}

Retweet a tweet

Retweet a single tweet.

Method: .retweet()

Endpoint: users/:loggedUserId/retweets (POST)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • tweetId: string: Tweet to retweet

Returns: TweetV2RetweetResult

Example

await client.v2.retweet('12', '20');

Unretweet a tweet

Remove a retweet of a single tweet.

Method: .unretweet()

Endpoint: users/:loggedUserId/retweets/:tweetId (DELETE)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • tweetId: string: Tweet to unretweet

Returns: TweetV2RetweetResult

Example

await client.v2.unretweet('12', '20');

List quote tweets of a tweet

Retrieve quote tweets for a single tweet using a paginator.

Method: .quotes()

Endpoint: tweets/:id/quote_tweets (GET)

Right level: Read-only

Arguments:

  • tweetId: string – ID of the tweet whose quote tweets you want.
  • options?: TweetV2PaginableTimelineParams – optional fields/expansions.

Returns: QuotedTweetsTimelineV2Paginator: A tweet paginator

Example

// Fetch quote tweets for a given tweet ID
const quotes = await client.v2.quotes('1456789', {
  expansions: ['author_id'],
  'user.fields': ['username', 'url'],
});

for await (const quote of quotes) {
  // Access the author using the paginator’s includes helper
  const author = quotes.includes.author(quote);
  if (author) {
    console.log(`${quote.id} quoted by ${author.username}`);
  }
}

Bookmarks

Bookmark a tweet

Add tweet as bookmark.

Method: .bookmark()

Endpoint: users/:id/bookmarks (POST)

Right level: Read-write

Arguments:

  • tweetId: string: Tweet to bookmark

Returns: TweetV2BookmarkResult

Example

await client.v2.bookmark('20')

Remove bookmark

Remove a bookmark by tweet ID.

Method: .deleteBookmark()

Endpoint: users/:id/bookmarks/:tweet_id (DELETE)

Right level: Read-write

Arguments:

  • tweetId: string: Tweet to unbookmark

Returns: TweetV2BookmarkResult

Example

await client.v2.deleteBookmark('20')

List bookmarks

List bookmarked tweets using a tweet paginator.

Method: .bookmarks()

Endpoint: users/:id/bookmarks (GET)

Right level: Read-only

Arguments:

  • options: TweetV2PaginableTimelineParams: Tweet meta options

Returns: TweetBookmarksTimelineV2Paginator: A tweet paginator

Example

const bookmarks = await client.v2.bookmarks({ expansions: ['referenced_tweets.id'] })

for await (const bookmark of bookmarks) {
  const quotedTweet = bookmarks.includes.quote(bookmark)

  if (quotedTweet) {
    console.log('Bookmarked tweet', bookmark.id, 'is a quote of', quotedTweet.id)
  }
}

Users

Logged user

Get the logged user.

Method: .me()

Endpoint: users/me

Right level: Read-only

Arguments:

  • options?: UsersV2Params

Returns: UserV2Result

Example

const meUser = await client.v2.me({ expansions: ['pinned_tweet_id'] });

// Request user's email (requires users.email OAuth 2.0 scope)
const meUserWithEmail = await client.v2.me({ 'user.fields': ['confirmed_email'] });
console.log(meUserWithEmail.data.confirmed_email); // user@example.com

Single user

Get a single user by ID.

Method: .user()

Endpoint: users/:id

Right level: Read-only

Arguments:

  • userId: string
  • options?: UsersV2Params

Returns: UserV2Result

Example

const jack = await client.v2.user('12', { 'tweet.fields': ['id', 'text'] });

Single user by username

Get a single user by username.

Method: .userByUsername()

Endpoint: users/by/username/:username

Right level: Read-only

Arguments:

  • username: string
  • options?: UsersV2Params

Returns: UserV2Result

Example

const jack = await client.v2.userByUsername('jack');

Users by id

Get users using a bunch of IDs.

Method: .users()

Endpoint: users

Right level: Read-only

Arguments:

  • userIds: string | string[]
  • options?: UsersV2Params

Returns: UsersV2Result

Example

const users = await client.v2.users(['12', '180248', '193208']);

Users by usernames

Get users using a bunch of usernames.

Method: .usersByUsernames()

Endpoint: users/by

Right level: Read-only

Arguments:

  • usernames: string | string[]
  • options?: UsersV2Params

Returns: UsersV2Result

Example

const users = await client.v2.usersByUsernames(['jack', 'plhery', 'alkihis']);

Get likes of a user

Return the last likes of a specific user. Get to know how paginators work here.

Method: .userLikedTweets()

Endpoint: users/:id/liked_tweets

Right level: Read-only

Arguments:

  • userId: string
  • options?: TweetV2PaginableListParams

Returns: TweetV2UserLikedTweetsPaginator

Example

const likedTweets = await client.v2.userLikedTweets('12');
console.log(likedTweets.tweets[0].id);

await likedTweets.fetchNext();

Followers

Get followers of a specific user ID.

Method: .followers()

Endpoint: users/:id/followers

Right level: Read-only

Arguments:

  • userId: string
  • options?: FollowersV2Params

Returns:

  • If asPaginator is absent or false in options: UserV2TimelineResult
  • If asPaginator is true in options: UserFollowersV2Paginator

Example

const followersOfJack = await client.v2.followers('12');

const followersOfJackAsPaginator = await client.v2.followers('12', { asPaginator: true });
console.log(followersOfJackAsPaginator instanceof UserFollowersV2Paginator) // true

Followings

Get followings (people who follows) of a specific user ID.

Method: .following()

Endpoint: users/:id/following

Right level: Read-only

Arguments:

  • userId: string
  • options?: FollowersV2Params

Returns:

  • If asPaginator is absent or false in options: UserV2TimelineResult
  • If asPaginator is true in options: UserFollowingV2Paginator

Example

const followingsOfJack = await client.v2.following('12');

const followingsOfJackAsPaginator = await client.v2.following('12', { asPaginator: true });
console.log(followingsOfJackAsPaginator instanceof UserFollowingV2Paginator) // true

Follow someone

Method: .follow()

Endpoint: users/:loggedUserId/following (POST)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to follow

Returns: UserV2FollowResult

Example

await client.v2.follow('12', '1903892');

Unfollow someone

Method: .unfollow()

Endpoint: users/:loggedUserId/following/:userId (DELETE)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to unfollow

Returns: UserV2UnfollowResult

Example

await client.v2.unfollow('12', '1903892');

Block someone

Method: .block()

Endpoint: users/:loggedUserId/blocking (POST)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to block

Returns: UserV2BlockResult

Example

await client.v2.block('12', '1903892');

Unblock someone

Method: .unblock()

Endpoint: users/:loggedUserId/blocking/:userId (DELETE)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to unblock

Returns: UserV2BlockResult

Example

await client.v2.unblock('12', '1903892');

Get users that are blocked by you

Get users blocked by the authenticating user. Get to know how paginators work here.

Method: .userBlockingUsers()

Endpoint: users/:id/blocking

Right level: Read-only

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • options?: UserV2TimelineParams

Returns: UserBlockingUsersV2Paginator

Example

const blockedPaginator = await client.v2.userBlockingUsers('14');

for await (const blockedUser of blockedPaginator) {
  console.log(`You are blocking @${blockedUser.username}.`);
}

Mute someone

Method: .mute()

Endpoint: users/:loggedUserId/muting (POST)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to mute

Returns: UserV2MuteResult

Example

await client.v2.mute('12', '1903892');

Unmute someone

Method: .unmute()

Endpoint: users/:loggedUserId/muting/:userId (DELETE)

Right level: Read-write

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • userId: string: User to unmute

Returns: UserV2MuteResult

Example

await client.v2.unmute('12', '1903892');

Get users that are muted by you

Get users muted by authenticated user. Get to know how paginators work here.

Method: .userMutingUsers()

Endpoint: users/:id/muting

Right level: Read-only

Arguments:

  • loggedUserId: string: Logged user (you) ID
  • options?: UserV2TimelineParams

Returns: UserMutingUsersV2Paginator

Example

const mutedPaginator = await client.v2.userMutingUsers('14');

for await (const mutedUser of mutedPaginator) {
  console.log(`You are muting @${mutedUser.username}.`);
}

Upload medias

Upload media

Method: .uploadMedia()

Endpoint: media/upload

Right level: Read-write

Arguments:

  • media: Buffer: Media buffer
  • options: MediaV2UploadParams
    • options.media_type: EUploadMimeType (the mimetype of the media)
    • options.media_category?: MediaV2MediaCategory (the category of the media)
    • options.chunkSize: Chunk size

Returns: string: Media ID

Example

const mediaId = await client.v2.uploadMedia(Buffer.from('image.png'), { media_type: 'image/png' });
const newTweet = await client.v1.tweet('Hello!', { media_ids: mediaId });

Upload media metadata

Method: .createMediaMetadata()

Endpoint: media/metadata

Right level: Read-write

Arguments:

  • mediaId: string
  • metadata: MediaV2MetadataCreateParams
    • metadata.alt_text: { text: string } the alt text of the media

Returns: MediaV2MetadataCreateResult

Example

await client.v2.createMediaMetadata(mediaId, { alt_text: { text: 'Hello, world!' } });

Get usage

Method: .usage()

Endpoint: usage/tweets

Right level: Read-only

Scope: App-only (no user OAuth scope required)

Arguments:

  • options: TweetUsageV2Params

usage.fields values: cap_reset_day, daily_client_app_usage, daily_project_usage, project_cap, project_id, project_usage.

Returns: TweetV2UsageResult

Example

const usage = await client.v2.usage({ 'usage.fields': ['project_usage', 'project_cap'] });

Example result

{
  "data": {
    "project_usage": "123",
    "project_cap": "1000"
  }
}

Lists

Single list by id

Method: .list()

Endpoint: lists/:id

Right level: Read-only

Arguments:

  • id: string
  • options: GetListV2Params

Returns: ListGetV2Result

Example

const aList = await client.v2.list('102', { expansions: ['owner_id'] });

Owned lists

Method: .listsOwned()

Endpoint: users/:id/owned_lists

Right level: Read-only

Arguments:

  • userId: string
  • options: GetListTimelineV2Params

Returns: UserOwnedListsV2Paginator (that contains ListV2 objects)

Example

// Get lists owned by me
const ownedLists = await client.v2.listsOwned((await client.v2.me()).data.id);

for await (const list of ownedLists) {
  console.log(list.id);
}

Lists with user as member

Method: .listMemberships()

Endpoint: users/:id/list_memberships

Right level: Read-only

Arguments:

  • userId: string
  • options: GetListTimelineV2Params

Returns: UserListMembershipsV2Paginator (that contains ListV2 objects)

Example

// Get lists owned by me inside
const listsWithMe = await client.v2.listMemberships((await client.v2.me()).data.id);

for await (const list of listsWithMe) {
  console.log(list.id);
}

Lists followed by an user

Method: .listFollowed()

Endpoint: users/:id/followed_lists

Right level: Read-only

Arguments:

  • userId: string
  • options: GetListTimelineV2Params

Returns: UserListFollowedV2Paginator (that contains ListV2 objects)

Example

// Get lists that I follow
const followedLists = await client.v2.listFollowed((await client.v2.me()).data.id);

for await (const list of followedLists) {
  console.log(list.id);
}

Tweet timeline of list

Method: .listTweets()

Endpoint: lists/:id/tweets

Right level: Read-only

Arguments:

  • listId: string
  • options: TweetV2PaginableListParams

Returns: TweetV2ListTweetsPaginator (that contains TweetV2 objects)

Example

const tweets = await client.v2.listTweets('102', { 'media.fields': ['media_key'], expansions: ['attachments.media_keys'] });

for await (const tweet of tweets) {
  console.log(tweet.id);
}

Members of a list

Method: .listMembers()

Endpoint: lists/:id/members

Right level: Read-only

Arguments:

  • listId: string
  • options: UserV2TimelineParams

Returns: UserListMembersV2Paginator (that contains UserV2 objects)

Example

const membersOfList = await client.v2.listMembers('102');

for await (const user of membersOfList) {
  console.log(user.id);
}

Followers of a list

Method: .listFollowers()

Endpoint: lists/:id/followers

Right level: Read-only

Arguments:

  • listId: string
  • options: UserV2TimelineParams

Returns: UserListFollowersV2Paginator (that contains UserV2 objects)

Example

const followersOfList = await client.v2.listFollowers('102');

for await (const user of followersOfList) {
  console.log(user.id);
}

Create a list

Method: .createList()

Endpoint: lists

Right level: Read-write

Arguments:

  • options: ListCreateV2Params

Returns: ListCreateV2Result

Example

const myNewList = await client.v2.createList({ name: 'cats', private: true });

Update list metadata

Method: .updateList()

Endpoint: lists/:id

Right level: Read-write

Arguments:

  • listId: string
  • options: ListUpdateV2Params

Returns: ListUpdateV2Result

Example

const updatedList = await client.v2.updateList('128492', { private: true });

Delete list

Method: .removeList()

Endpoint: lists/:id

Right level: Read-write

Arguments:

  • listId: string

Returns: ListDeleteV2Result

Example

await client.v2.removeList('128492');

Add list member

Method: .addListMember()

Endpoint: lists/:id/members

Right level: Read-write

Arguments:

  • listId: string
  • userId: string

Returns: ListMemberV2Result

Example

await client.v2.addListMember('12', '128492');

Remove list member

Method: .removeListMember()

Endpoint: lists/:id/members/:user_id

Right level: Read-write

Arguments:

  • listId: string
  • userId: string

Returns: ListMemberV2Result

Example

await client.v2.removeListMember('128492', '12');

Subscribe to a list

Method: .subscribeToList()

Endpoint: users/:id/followed_lists

Right level: Read-write

Arguments:

  • loggedUserId: string
  • listId: string

Returns: ListFollowV2Result

Example

await client.v2.subscribeToList('12', '128492');

Unsubscribe of a list

Method: .unsubscribeOfList()

Endpoint: users/:id/followed_lists/:list_id

Right level: Read-write

Arguments:

  • loggedUserId: string
  • listId: string

Returns: ListFollowV2Result

Example

await client.v2.unsubscribeOfList('12', '128492');

Pin a list

Method: .pinList()

Endpoint: users/:id/pinned_lists

Right level: Read-write

Arguments:

  • loggedUserId: string
  • listId: string

Returns: ListPinV2Result

Example

await client.v2.pinList('12', '128492');

Unpin a list

Method: .unpinList()

Endpoint: users/:id/pinned_lists/:list_id

Right level: Read-write

Arguments:

  • loggedUserId: string
  • listId: string

Returns: ListPinV2Result

Example

await client.v2.unpinList('12', '128492');

Spaces

Space by id

Get a single space by its ID.

Method: .space()

Endpoint: spaces/:id

Right level: Read-only

Arguments:

  • spaceId: string
  • options?: SpaceV2FieldsParams

Returns: SpaceV2SingleResult

Example

const { data: space } = await client.v2.space('space-id')
// space is a SpaceV2
console.log(space.state) // 'live'

Spaces by id

Get spaces by its ID.

Method: .spaces()

Endpoint: spaces

Right level: Read-only

Arguments:

  • spaceIds: string | string[]
  • options?: SpaceV2FieldsParams

Returns: SpaceV2LookupResult

Example

const { data: spaces } = await client.v2.spaces('space-id,space-2-id')
console.log(spaces) // SpaceV2[]

Spaces by their creator id

Get spaces users who created them. (No pagination available)

Method: .spacesByCreators()

Endpoint: spaces/by/creator_ids

Right level: Read-only

Arguments:

  • creatorUserIds: string | string[]
  • options?: SpaceV2FieldsParams

Returns: SpaceV2LookupResult

Example

const { data: spaces } = await client.v2.spacesByCreators(['12', '1024'])
console.log(spaces) // SpaceV2[] - Spaces of users '12' and '1024'

Search spaces

Search spaces using a query (will be looked up in their title) and their state. (No pagination available)

Method: .searchSpaces()

Endpoint: spaces/search

Right level: Read-only

Arguments:

  • options: SpaceV2SearchParams

Returns: SpaceV2LookupResult

Example

const { data: spaces } = await client.v2.searchSpaces({ query: 'Node JS', state: 'live' })
console.log(spaces) // SpaceV2[] - Found live spaces talking about NodeJS!

Space buyers

Get buyers of your space by its ID.

Method: .spaceBuyers()

Endpoint: spaces/:id/buyers

Right level: Read-only

Arguments:

  • spaceId: string
  • options?: SpaceV2BuyersParams

Returns: SpaceV2BuyersResult

Example

const { data: users } = await client.v2.spaceBuyers('space-id')
// users is a UserV2[]

Space tweets

Get tweets of your space by its ID.

Method: .spaceTweets()

Endpoint: spaces/:id/tweets

Right level: Read-only

Arguments:

  • spaceId: string
  • options?: Tweetv2FieldsParams

Returns: TweetV2LookupResult

Example

const { data: tweets } = await client.v2.spaceTweets('space-id')
// tweets is a TweetV2[]

Communities

Community by id

Returns a variety of information about a single Community specified by ID.

Method: .community()

Endpoint: communities/:id

Right level: Read-only

Arguments:

  • communityId: string
  • options?: CommunityByIDV2Params

Returns: CommunityV2Result

Example

const { data: community } = await client.v2.community('12345', {
  expansions: ['creator_id'],
});

Search communities

Search for Communities based on keywords.

Method: .searchCommunities()

Endpoint: communities/search

Right level: Read-only

Arguments:

  • query: string
  • options?: CommunitySearchV2Params

Returns: CommunitiesV2Result

Example

const { data: communities } = await client.v2.searchCommunities('typescript');

Direct messages (DMs)

Fetch direct message events (without filter)

Returns a list of Direct Messages for the authenticated user, both sent and received.

Method: .listDmEvents()

Endpoint: dm_events

Right level: Read-only

Arguments:

  • options?: GetDMEventV2Params

Returns: FullDMTimelineV2Paginator (containing DMEventV2)

Example

const eventTimeline = await client.v2.listDmEvents()
console.log(eventTimeline.events)

Fetch direct message events by participant id

Returns a list of Direct Messages (DM) events within a 1-1 conversation with the user specified.

Method: .listDmEventsWithParticipant()

Endpoint: dm_conversations/with/:participant_id/dm_events

Right level: Read-only

Arguments:

  • participantId: string
  • options?: GetDMEventV2Params

Returns: OneToOneDMTimelineV2Paginator (containing DMEventV2)

Example

const eventTimeline = await client.v2.listDmEventsWithParticipant('12')
console.log(eventTimeline.events)

Fetch direct message events by conversation id

Returns a list of Direct Messages (DM) events within a 1-1 conversation with the user specified.

Method: .listDmEventsOfConversation()

Endpoint: dm_conversations/:dm_conversation_id/dm_events

Right level: Read-only

Arguments:

  • dmConversationId: string
  • options?: GetDMEventV2Params

Returns: ConversationDMTimelineV2Paginator (containing DMEventV2)

Example

const eventTimeline = await client.v2.listDmEventsOfConversation('12')
console.log(eventTimeline.events)

Create a group conversation

Creates a new group conversation and adds a Direct Message to it on behalf of an authenticated user.

Method: .createDmConversation()

Endpoint: dm_conversations

Right level: Read-write

Arguments:

  • options: CreateDMConversationParams

Returns: PostDMInConversationResult

Example

const { dm_conversation_id, dm_event_id } = await client.v2.createDmConversation({
	conversation_type: 'Group',
	participant_ids: ['12', '24'],
	message: {
        text: 'Hello!',
		attachments: [{ media_id: '123' }],
	},
})

Create a new one-to-one direct message (and the conversation if applicable)

Creates a one-to-one Direct Message and adds it to the one-to-one conversation. If the conversation does not exists, it creates it.

Method: .sendDmToParticipant()

Endpoint: dm_conversations/with/:participant_id/messages

Right level: Read-write

Arguments:

  • participantId: string
  • options: PostDMInConversationParams

Returns: PostDMInConversationResult

Example

const { dm_conversation_id, dm_event_id } = await client.v2.sendDmToParticipant('12', {
	text: 'Hello!',
	attachments: [{ media_id: '123' }],
})

Create a new direct message in a known conversation

Creates a Direct Message on behalf of an authenticated user, and adds it to the specified conversation.

Method: .sendDmInConversation()

Endpoint: dm_conversations/:dm_conversation_id/messages

Right level: Read-write

Arguments:

  • conversationId: string
  • options: PostDMInConversationParams

Returns: PostDMInConversationResult

Example

const { dm_event_id } = await client.v2.sendDmInConversation('19732-4843', {
	text: 'Hello!',
})

Batch compliance

Get a single compliance job

Get a already created compliance job.

Method: .complianceJob()

Endpoint: compliance/jobs/:id (GET)

Right level: Read-only

Arguments:

  • jobId: string: Job ID

Returns: BatchComplianceV2Result

Example

const job = await client.v2.complianceJob('289859');
console.log(job.data.status); // 'in_progress'

Search compliance jobs

Get a list of compliance jobs by type and status.

Method: .complianceJobs()

Endpoint: compliance/jobs (GET)

Right level: Read-only

Arguments:

  • options: BatchComplianceSearchV2Params: Options

Returns: BatchComplianceListV2Result

Example

const jobs = await client.v2.complianceJobs({ type: 'tweets' });
console.log(jobs.data[0].status); // 'in_progress'

Create a new compliance job

Create new compliance job given a user/tweet ID list.

Method: .sendComplianceJob()

Endpoint: compliance/jobs (POST)

Right level: Read-only

Arguments:

  • options: BatchComplianceV2Params: Job options

Returns: BatchComplianceV2Result

Example

// Create the job
const createdJob = await client.v2.sendComplianceJob({
  type: 'tweets',
  ids: ['20', '1430917443426336770', '1430914940559372289', '1298636084130336773'],
});
// Await the job result
const jobResult = await client.v2.complianceJobResult(createdJob.data);

Get compliance job result

Await job resolution (can be very long), download the result and parse it.

Method: .complianceJobResult()

Right level: Read-only

Arguments:

  • job: BatchComplianceJobV2: Job (extracted from BatchComplianceV2Result/BatchComplianceListV2Result)

Returns: BatchComplianceV2JobResult

Example

// Create the job
const createdJob = await client.v2.sendComplianceJob({
  type: 'tweets',
  ids: ['20', '1430917443426336770', '1430914940559372289', '1298636084130336773'],
});
// Await the job result
const jobResult = await client.v2.complianceJobResult(createdJob.data);

for (const tweetCompliance of jobResult) {
  // Job result is parsed into an array
  console.log(`#${tweetCompliance.id}: action ${tweetCompliance.action} because ${tweetCompliance.reason}`);
}