Twitter API Integration (RSSHub)#

Overview#

RSSHub's Twitter integration lives under lib/routes/twitter/ and converts X (Twitter) timelines, lists, searches, and conversations into RSS feeds. All active routes use the web-api path, making GraphQL requests to https://x.com/i/api 1. The mobile API was removed in October 2025 after Twitter introduced client attestation 2; the developer (Pay-Per-Use) API remains available for user and keyword routes.

Required configuration (at least one auth method):

Route Map#

The id parameter for user routes accepts either a screen name or a unique numeric ID prefixed with + (e.g., +44196397) 11.

Universal routeParams options (query-string format) include display controls (readable, authorNameBold, showAuthorInTitle, etc.) and feed-shaping flags 12:

• includeReplies / includeRts — only for /twitter/user
• forceWebApi — forces web-api even when a developer API key is configured, available for /twitter/user and /twitter/keyword
• count — passed directly to the Twitter API

Authentication & Request Flow#

All web-api calls go through twitterGot in utils.ts, which uses undici.fetch directly — not ofetch or the global request rewriter — to preserve the CookieAgent dispatcher. This was a critical production fix: the standard Request constructor silently drops the dispatcher option, causing cookies to never be sent 13.

Token selection and cookie hydration:

1. getAuth round-robins across the TWITTER_AUTH_TOKEN list. Each token is locked under the cache key twitter:lock-token1:<token> (TTL 20 s) to prevent concurrent reuse.
2. token2Cookie wraps the token in a CookieJar, fetches https://x.com to hydrate session cookies, and caches the result under twitter:cookie:<token>.

For third-party API mode (TWITTER_THIRD_PARTY_API), requests are routed through ofetch to the proxy endpoint instead of twitterGot. This mode only covers the operations listed in thirdPartySupportedAPI 6: UserByScreenName, UserByRestId, UserTweets, UserTweetsAndReplies, ListLatestTweetsTimeline, SearchTimeline, UserMedia.

GraphQL Query ID Resolution#

Twitter rotates GraphQL query IDs every 2–4 weeks, breaking all routes with 404 errors. gql-id-resolver.ts (introduced in PR #21544) resolves this dynamically:

1. Fetches https://x.com HTML and extracts the client-web/main.<hash>.js bundle URL 14.
2. Downloads the bundle and regex-extracts all queryId/operationName pairs 15.
3. Caches the result under twitter:gql-query-ids using config.cache.contentExpire 16.
4. Falls back to hardcoded IDs if extraction fails 17.

A shared resolvePromise deduplicates concurrent resolution attempts during startup 18. The resolved map is built via buildGqlMap(), which produces paths like /graphql/<id>/<OperationName> 19.

constants.ts initializes gqlMap from fallbackIds at module load and rebuilds it via initGqlMap(), which is wired as api.init() and called before the first API request 20.

Covered operations and their fallback IDs 21:

Cache Key Isolation#

Bug (issue #22864): getUserTweets, getUserTweetsAndReplies, and getUserMedia all passed anonymous arrow functions as callbacks to cacheTryGet. Because Function.name is "" for anonymous functions, all three operations produced the same cache key — twitter:<rest_id>::{"count":17} — causing one operation's results to be served for another.

Fix (commit 6a265e9d8): cacheTryGet now accepts an explicit operationName string as its third argument:

cache.tryGet(getTwitterUserCacheKey(id, operationName, params), ...)

Each operation passes its own string literal 22:

User profile data is cached separately under twitter-userdata-${id} 23, independent of timeline operations.

Timeline & Conversation Parsing#

All timeline data flows through gatherLegacyFromData(entries, filterNested?, userId?) in web-api/utils.ts. It filters the raw GraphQL instruction entries in two passes:

1. Direct tweets: entries with entryId starting with tweet- or profile-grid-0-tweet- are included as-is 24.
2. Nested conversation modules: if filterNested is provided, entries whose entryId matches any prefix have their entry.content.items expanded and flattened into the result 25.

Per-operation filterNested prefixes 26:

Known bug and fix (issue #19788): The list timeline parser was dropping tweets contained in listConversation-* modules — including an author's own follow-up posts. The fix (commit b879d8d7f) passes ['listConversation-'] as filterNested to gatherLegacyFromData so those modules are expanded rather than skipped.

Special content types handled inside gatherLegacyFromData:

• Long-form notes (note_tweet): full_text is replaced with the note body and entities are re-extracted 27.
• Subscriber-only previews (TweetPreviewDisplay): a synthetic legacy object is constructed with a [Subscribers Only] prefix so the entry still appears in the feed 28.