twitter-api-v2

Paginators handle rate limits automatically during .fetchLast() calls or when using async iteration; the process will simply end when a rate limit is encountered. You can also check the current rate limit status for the paginator's endpoint using the .rateLimit getter.

const paginator = await client.v1.homeTimeline();
console.log(paginator.rateLimit); // { limit: number, remaining: number, reset: number }

All Twitter API v2 methods are attached to the v2 property of the client instance. You access them via client.v2.

If a specific endpoint is not implemented in the package, you can perform manual requests using the generic HTTP wrapper methods: .get(), .post(), .put(), .patch(), and .delete().

Key technical notes:

• Arguments: Described arguments usually refer to an interface name. The actual argument type is typically a Partial<InterfaceName>, meaning all properties are optional.
• Return Types: All API methods return Promises.
• Data Inclusion: The API uses includes to attach related data (like media, polls, or users) to responses. Use the includes helper to browse these attached entities.

Because the library supports multiple versions of the Twitter API, you must specify which version you intend to use to access the correct endpoint-wrapper methods. Using a versioned client automatically applies the correct URL prefix.

• v1 Client: client.v1 (Prefix: https://api.x.com/1.1/)
• v2 Client: client.v2 (Prefix: https://api.x.com/2/)
• v2 Labs Client: client.v2.labs (Prefix: https://api.x.com/labs/2/)

const v1Client = client.v1;
const v2Client = client.v2;
const v2LabsClient = client.v2.labs;

All Twitter API v1.1 methods are attached to the v1 property of your client instance. To use them, access them through client.v1.

If a specific endpoint is not implemented as a dedicated method, you can still make manual requests using the generic HTTP wrapper methods: .get(), .post(), .put(), .patch(), and .delete().

By default, streaming methods connect immediately and return a Promise that resolves to the stream. If you want to configure event handlers before the connection starts, or if you want the method to return the TweetStream object synchronously, pass { autoConnect: false } in the options object.

You must then manually call .connect() to start the stream. This is useful for setting up complex reconnection logic or specific event listeners upfront.

const stream = client.v2.sampleStream({ autoConnect: false });

stream.on(ETwitterStreamEvent.Data, console.log);
stream.on(ETwitterStreamEvent.Connected, () => console.log('Stream is started.'));

await stream.connect({ autoReconnect: true, autoReconnectRetries: Infinity });

In Twitter API v2, expanded metadata (like user objects or media) is returned in an includes object rather than directly within the primary data array. To avoid manual searching and handling undefined values, use the TwitterV2IncludesHelper class.

Simple Usage

Instantiate the helper by passing the full API response object. The helper provides fail-safe getters for all include types (tweets, media, users, polls, and places), ensuring they are always defined even if the response lacks them.

Static Usage

You can also use the helper without instantiation by calling its methods statically. The pattern is MethodName(responseObject, ...restParameters).

Example:

TwitterV2IncludesHelper.tweets(response)
TwitterV2IncludesHelper.retweets(response, tweet)

You can extend the twitter-api-v2 client using official plugins. Common plugins include:

• @twitter-api-v2/plugin-token-refresher: Automatically handles OAuth 2.0 (user-context) token refreshing.
• @twitter-api-v2/plugin-rate-limit: Provides access to and storage for automatic rate limit data.
• @twitter-api-v2/plugin-cache-redis: Enables caching of responses using a Redis store.

Endpoints that return paginable collections (such as user timelines, tweet searches, or home timelines) return a subclass of TwitterPaginator.

When you call a paginable method, the instance is initialized with the first page of data. You can then use various methods to navigate through subsequent pages of results. Paginators support both cumulative fetching (adding new items to the existing instance) and discrete fetching (getting a new instance for the next page).

const homeTimeline = await client.v1.homeTimeline();

When a request fails, you can catch one of three error types, all of which are instances of Error. Identifying the type helps determine if the issue is local, connection-based, or returned by Twitter.

• ApiRequestError: The request failed to be sent (e.g., network error, invalid URL).
• ApiPartialResponseError: The response was partially received, but the connection was closed (by the client, OS, or Twitter) before completion.
• ApiResponseError: Twitter successfully received the request and replied with an error (e.g., 401 Unauthorized, 404 Not Found).

Common properties across these error types:

• error: true
• type: Contains ETwitterApiError.Request, ETwitterApiError.PartialResponse, or ETwitterApiError.Response.
• request: The raw Node.js ClientRequest instance.