Post-Mortem: X's SearchTimeline Rotated and user.legacy Was Removed
An hour-by-hour technical post-mortem of the 2026-11-21 X Web GraphQL break, with a complete field-mapping reference and a drop-in defensive parser.
How this analysis was produced. All timestamps, failure signatures, and payload-shape observations in this post come from one of three sources: (1) TwitterAPI.io's own gateway telemetry, which continuously probes the X.com Web GraphQL surface with rotated browser fingerprints to detect and absorb upstream changes; (2) direct inspection of X's current web bundle for the live queryId, features dictionary, and x-client-transaction-id algorithm; (3) the public issue trackers of the open-source libraries listed in the status table below, cross-referenced to confirm each symptom is reproducible outside our own stack. Where we quote a specific error string, that string appears verbatim in at least one maintainer-filed issue on the relevant repository.
At a glance
- Incident start
- 2026-11-21, ~03:50 UTC
- Scope
- X.com internal Web GraphQL SearchTimeline + embedded user_results
- Observed symptoms
- HTTP 404 on search · KeyError: 'legacy' · undefined screen_name · burner suspensions
- Confirmed broken OSS libs
- twscrape · twikit · Rettiwt-API · agent-twitter-client · RSSHub
- X API Basic tier
- Unaffected (different endpoint family)
- TwitterAPI.io status
- 0 schema breaking changes · normalized response unchanged · $0 on failed calls
If your production X (Twitter) data pipeline, AI agent, or monitoring cronjob suddenly started throwing HTTP 404 on SearchTimeline, KeyError: 'legacy', Cannot read properties of undefined (reading 'screen_name'), or mass account suspensions beginning at ~03:50 UTC on 2026-11-21, it is not a local network issue. X shipped one of its largest Web GraphQL updates of 2026 and simultaneously broke every open-source library that calls the internal search endpoint directly. This post reconstructs the full incident, maps every field that moved, and gives you two safe ways out.
Timeline (all times UTC)
The following hour-by-hour reconstruction is pieced together from TwitterAPI.io gateway telemetry, direct observation of the X.com web bundle during the incident window, and the first wave of maintainer-filed issues on the affected open-source repositories.
- 2026-11-21 03:50 UTCT+0
First HTTP 404 on SearchTimeline observed in TwitterAPI.io gateway telemetry. Every existing SearchTimeline queryId stops resolving across all egress IP ranges simultaneously, consistent with a server-side operation-hash rotation rather than regional rollout.
- 2026-11-21 03:52 – 04:05 UTC+2 – +15 min
404 spreads to every Web client fingerprint we rotate (Chrome, Edge, Firefox; macOS, Windows, Linux). No 200 responses from any legacy queryId in this window — ruling out any gradual canary.
- 2026-11-21 04:10 – 04:40 UTC+20 – +50 min
First bug reports appear on the public issue trackers of the open-source libraries that call X's Web GraphQL directly. Reports converge on identical error signatures across libraries written in Python, TypeScript, and Rust — a strong signal the break is upstream, not in any one lib.
- 2026-11-21 04:45 – 05:30 UTC+55 – +1h 40
Maintainers extract the new queryId and features flag dictionary from the live X.com bundle. A second failure mode now emerges: parsers that successfully send the new request crash with KeyError: 'legacy' when reading core.user_results.result — X has simultaneously removed user.legacy from SearchTimeline responses (tweet.legacy remains).
- 2026-11-21 06:00 – 09:00 UTC+2h – +5h
First wave of 'inauthentic behavior' suspensions. Burner-account pools that retried failing SearchTimeline requests in tight loops — the default retry policy of most libraries — trip the automated anti-automation sweep. Operators report mass session invalidation and Arkose challenge locks.
- 2026-11-21 09:30 – 14:00 UTC+6h – +10h
Partial patches land in several maintainers' main branches. Most address the queryId / features rotation but not the user.legacy removal, so downstream apps report 'request succeeds, parser still crashes' on upgrade.
- 2026-11-21 14:00 UTC onward+10h+
x-client-transaction-id generation tightens further. Libraries that extract the transaction-id algorithm from the web bundle report a second-order break as the extraction regex also needs updating.
- 2026-11-22 (publication)+24h
Most libraries ship first-pass fixes. Full user.legacy → split sub-object mapping has not been published by any OSS maintainer in a single place; this post is the first complete field-mapping reference we're aware of. Burner suspensions continue in waves as sweeps catch earlier retry bursts retroactively.
The three breaking changes, in depth
1. SearchTimeline GraphQL queryId + features + x-client-transaction-id all rotated
X's internal Web GraphQL endpoint for SearchTimeline is served at a URL of the shape https://x.com/i/api/graphql/<queryId>/SearchTimeline. The queryId segment is the operation hash: it changes whenever the web client bundle ships a new version of the query. On 2026-11-21 at ~03:50 UTC, three things rotated simultaneously:
- The
queryIditself. Every library that hardcoded the previous hash gets HTTP 404 on every call, because the previous URL no longer resolves to any operation. - The required
featuresdictionary. X's GraphQL endpoints read a JSON object of feature flags (dozens of boolean toggles likeresponsive_web_graphql_exclude_directive_enabledandverified_phone_label_enabled). Server-side validation now rejects requests with the stale dictionary — observed as HTTP 500 in a subset of failure modes where thequeryIdwas updated but thefeaturespayload was not. - The
x-client-transaction-idalgorithm. X's web client computes a per-request transaction ID derived from the current URL and the running bundle's secret state. Libraries that extract this algorithm from the live bundle report a second-order failure (ClientTransactionNotInitializedError) because the regex they use to locate the code chunk no longer matches the minified output.
2. The entire user.legacy object disappeared from SearchTimeline responses
Even once a library has updated its queryId, features dictionary, and transaction ID extraction, downstream parsers keep crashing. The reason is that X restructured the embedded author object at tweet_results.result.core.user_results.result:
- Tweet fields (
full_text,created_at,favorite_count,retweet_count,entities) remain insidetweet.legacyat their previous paths. If your tweet parser crashes, the bug is somewhere else. - Author fields (
user.legacy) have been completely removed fromSearchTimelineresponses. The fields that used to live underuser.legacyhave been split across dedicated sub-objects:core,avatar,relationship_counts,tweet_counts,profile_bio,verification, andlocation. The complete mapping is in section 03 below.
3. "Inauthentic behavior" sweep caught libraries that retried in a tight loop
The default retry policy of most open-source scrapers — back off, rotate account, retry — produced a recognizable, patterned failure-retry sequence on 2026-11-21 across every cooperating burner account in a pool. X's anti-automation sweep correlates such sequences across sessions and subjects them to Arkose challenge, account lock, or outright termination for "inauthentic behavior." Cookie pools maintained by twscrape and agent-twitter-client operators report multi-hour loss of a double-digit percentage of accounts in the +2h – +5h window. This is not a bug in those libraries; it is the operational consequence of running on X-visible authenticated sessions when X itself has just changed the rules.
Field mapping: user.legacy → split sub-objects
If you are patching an internal GraphQL parser, update your author extractor (user = entry.content.itemContent.tweet_results.result.core.user_results.result) with the fallback mapping below. The table is the complete set of fields observed in both shapes; any field not listed here (for example user.rest_id or user.is_blue_verified) is unchanged.
| Author field | Pre-2026-11-21 | Post-2026-11-21 | Notes |
|---|---|---|---|
| User ID | user.rest_id | user.rest_id | Unchanged |
| Username (@handle) | user.legacy.screen_name | user.core.screen_name | user.legacy is now undefined |
| Display Name | user.legacy.name | user.core.name | Moved to user.core |
| Account Created At | user.legacy.created_at | user.core.created_at | Moved to user.core |
| Avatar URL | user.legacy.profile_image_url_https | user.avatar.image_url | Moved to user.avatar |
| Followers Count | user.legacy.followers_count | user.relationship_counts.followers | Integer |
| Following Count | user.legacy.friends_count | user.relationship_counts.following | Integer |
| Total Tweets Count | user.legacy.statuses_count | user.tweet_counts.tweets | Integer |
| Media Tweets Count | user.legacy.media_count | user.tweet_counts.media_tweets | Integer |
| Bio / Description | user.legacy.description | user.profile_bio.description | String |
| Location | user.legacy.location | user.location.location | Check dict / string |
| Blue Verified | user.is_blue_verified | user.is_blue_verified | Boolean |
| Legacy / Org Verified | user.legacy.verified | user.verification.verified | Boolean |
Drop-in defensive parser — Python
Works against both the old user.legacy object and the new split sub-objects, so you can roll it out before you've finished confirming which upstream shape you'll see next.
def extract_author_safe(user_obj: dict) -> dict:
"""Extract an author record from an X/Twitter Web GraphQL user_results.result.
Handles BOTH the pre-2026-11-21 shape (fields under user.legacy) AND the
post-2026-11-21 shape (fields split across core / avatar /
relationship_counts / tweet_counts / profile_bio / verification / location).
Safe to deploy before you know which shape your upstream will serve you
next: the helper falls back through both layouts and never raises on a
missing key.
"""
legacy = user_obj.get("legacy") or {}
core = user_obj.get("core") or {}
rel = user_obj.get("relationship_counts") or {}
counts = user_obj.get("tweet_counts") or {}
avatar = user_obj.get("avatar") or {}
bio = user_obj.get("profile_bio") or {}
verif = user_obj.get("verification") or {}
loc = user_obj.get("location")
# location can be a dict ({"location": "..."}), a string, or missing — all
# three have been observed since 2026-11-21.
location_str = (
loc.get("location", "") if isinstance(loc, dict)
else (loc if isinstance(loc, str) else legacy.get("location", ""))
)
return {
"id": user_obj.get("rest_id"),
"userName": core.get("screen_name") or legacy.get("screen_name") or "",
"name": core.get("name") or legacy.get("name") or "",
"createdAt": core.get("created_at") or legacy.get("created_at") or "",
"profilePicture": avatar.get("image_url") or legacy.get("profile_image_url_https") or "",
"followers": rel.get("followers") if "followers" in rel else legacy.get("followers_count", 0),
"following": rel.get("following") if "following" in rel else legacy.get("friends_count", 0),
"statusesCount": counts.get("tweets") if "tweets" in counts else legacy.get("statuses_count", 0),
"description": bio.get("description") or legacy.get("description") or "",
"location": location_str,
"isBlueVerified": bool(user_obj.get("is_blue_verified")),
"isVerified": bool(verif.get("verified") or legacy.get("verified")),
}Drop-in defensive parser — Node / TypeScript
Semantics identical to the Python helper. Drop into a utility file, import from your tweet-processing hot path.
// Node / TypeScript equivalent. Works unchanged against both the pre- and
// post-2026-11-21 X Web GraphQL user_results.result payload shapes.
export function extractAuthorSafe(user: any) {
const legacy = user?.legacy ?? {}
const core = user?.core ?? {}
const rel = user?.relationship_counts ?? {}
const counts = user?.tweet_counts ?? {}
const avatar = user?.avatar ?? {}
const bio = user?.profile_bio ?? {}
const verif = user?.verification ?? {}
const loc = user?.location
const location =
typeof loc === "object" && loc !== null ? loc.location ?? "" :
typeof loc === "string" ? loc :
legacy.location ?? ""
return {
id: user?.rest_id,
userName: core.screen_name ?? legacy.screen_name ?? "",
name: core.name ?? legacy.name ?? "",
createdAt: core.created_at ?? legacy.created_at ?? "",
profilePicture: avatar.image_url ?? legacy.profile_image_url_https ?? "",
followers: "followers" in rel ? rel.followers : legacy.followers_count ?? 0,
following: "following" in rel ? rel.following : legacy.friends_count ?? 0,
statusesCount: "tweets" in counts ? counts.tweets : legacy.statuses_count ?? 0,
description: bio.description ?? legacy.description ?? "",
location,
isBlueVerified: Boolean(user?.is_blue_verified),
isVerified: Boolean(verif.verified ?? legacy.verified),
}
}Open-source libraries confirmed broken
The following libraries all call X's internal Web GraphQL SearchTimeline endpoint directly and are therefore affected by the 2026-11-21 rotation. The repository tabs linked below are the authoritative sources for each maintainer's progress. Links carry rel="nofollow" per our citation policy; please read them on the maintainers' own repositories rather than caching the text.
| Library | Language | Observed status | Repository |
|---|---|---|---|
| twscrape | Python | Broken: SearchTimeline 404 + burner account suspension waves. See the repo's issues tab for maintainer updates and PRs. | GitHub |
| twikit | Python | Broken: ClientTransactionNotInitializedError + KeyError: 'legacy'. Workaround threads tracked in the repo's issues tab. | GitHub |
| Rettiwt-API | TypeScript | Broken: tweet.search returns HTTP 404. Patch effort visible on the repo's recent commits. | GitHub |
| agent-twitter-client | TypeScript | Broken: search() rejects with HTTP 404; cookie-session flows subject to the inauthentic-behavior sweep. | GitHub |
| RSSHub | TypeScript | Partially broken: X routes that rely on the Web GraphQL search path fail; routes using alternative data sources are unaffected. | GitHub |
A library not on this list (for example, one that only wraps the Official X API tiers) is not affected by this incident. If you are seeing errors on another library that calls the internal Web GraphQL and is not listed here, the mapping table in section 03 and the defensive parsers above still apply; they are library-agnostic.
Why self-hosted cookie pools no longer make economic sense
Even after patching the JSON schema, running twscrape, twikit, or agent-twitter-client in production still requires:
- 1Buying and warming aged X accounts, which now get swept in waves during every upstream rotation under X's current "inauthentic behavior" policy.
- 2Paying
$3 – $8 / GBfor clean residential proxies: raw uncompressed X GraphQL responses average 110 – 210 KB per 20-tweet page. - 3Reverse-engineering
x-client-transaction-id, thefeaturesdictionary, and rotatedqueryIdvalues every few weeks whenever an on-call alert fires at 2 AM. - 4Absorbing the recurring operational cost of running a mini anti-detection team whose entire job is to stay one step ahead of a vendor with more engineers than your scraper project has contributors.
| Approach | Real cost | Schema stability | Ban risk |
|---|---|---|---|
| Official X API (Basic / Pro / Enterprise) | $200 – $5,000+ / mo | Stable, with documented versioning | None |
| DIY open-source (twscrape / twikit / Rettiwt-API / agent-twitter-client / RSSHub) | Burner accounts + residential proxies ($3–$8/GB) + on-call engineering | Breaks on every X.com Web GraphQL rotation | High — mass suspensions, Arkose locks, device fingerprint flags |
| TwitterAPI.io (managed normalized API) | $0.15 per 1,000 tweets · $0 on failed calls | Normalized & backward-compatible | Zero (no X accounts needed) |
Restore production X search in 60 seconds (zero schema breakage)
At TwitterAPI.io we absorb upstream X GraphQL changes at our gateway layer and normalize every response into a stable JSON contract. Our customers didn't rewrite user.legacy parsers on 2026-11-21, and failed (non-200) requests are never billed ($0).
Direct curl example (Latest + full search operators)
curl -G "https://api.twitterapi.io/twitter/tweet/advanced_search" \ --data-urlencode 'query=(openai OR anthropic) min_faves:20 lang:en' \ --data-urlencode 'queryType=Latest' \ -H "X-API-Key: YOUR_TWITTERAPI_KEY"
30-second Cursor / Claude Code migration prompt
Paste this straight into your coding agent and have a broken scraper replaced in place:
Replace our broken X/Twitter scraper (twscrape / twikit / Rettiwt-API / agent-twitter-client / RSSHub) search calls with: GET https://api.twitterapi.io/twitter/tweet/advanced_search?query=...&queryType=Latest Header: X-API-Key: process.env.TWITTERAPI_IO_KEY Paginate: pass the response's next_cursor field back as the "cursor" query param. Author access: response.tweets[i].author.userName / .followers / .profilePicture (already normalized — no user.legacy, no core.*, no relationship_counts.*). Failed calls: $0. Minimum successful call: 15 credits ($0.00015). Docs: https://docs.twitterapi.io/api-reference/endpoint/tweet-advanced-search
Frequently asked questions
When exactly did the X SearchTimeline break on November 21, 2026?
The first SearchTimeline HTTP 404 was observed in TwitterAPI.io gateway telemetry at approximately 03:50 UTC on 2026-11-21. Within 15 minutes every legacy queryId had stopped resolving across every Web client fingerprint we rotate, consistent with a server-side operation-hash rotation rather than a regional canary. First open-source bug reports appeared between 04:10 and 04:40 UTC. A second failure mode — KeyError: 'legacy' at tweet_results.result.core.user_results.result — emerged between 04:45 and 05:30 UTC once libraries had updated the queryId and could successfully reach the endpoint. The first wave of 'inauthentic behavior' suspensions started around 06:00 UTC.
Which open-source scraping libraries are affected?
Every open-source library that calls X's internal Web GraphQL SearchTimeline operation directly: twscrape (Python, github.com/vladkens/twscrape), twikit (Python, github.com/d60/twikit), Rettiwt-API (TypeScript, github.com/Rishikant181/Rettiwt-API), agent-twitter-client (TypeScript, github.com/elizaOS/agent-twitter-client), and RSSHub (TypeScript, github.com/DIYgod/RSSHub) on X routes that use the search path. Libraries that only read the Official X API are not affected, because the Official API is a separate endpoint family and has its own versioning contract.
Why is X SearchTimeline returning 404 since 03:50 UTC on 2026-11-21?
X rotated the GraphQL queryId (the operation hash in the URL path), tightened server-side validation on the required features flag dictionary, and tightened the x-client-transaction-id header verification. Any client that hardcoded the previous queryId or ships an out-of-date features dictionary gets HTTP 404 on the endpoint and, in some variants, HTTP 500 after passing the path check but failing feature-flag validation.
Why did user.legacy.screen_name and followers_count become undefined?
On 2026-11-21, X removed the legacy object from core.user_results.result inside SearchTimeline responses. The embedded tweet object still has tweet.legacy (full_text, created_at, favorite_count, retweet_count, entities are all still there), but the author side has been split across dedicated sub-objects: user.core (screen_name, name, created_at), user.avatar (image_url), user.relationship_counts (followers, following), user.tweet_counts (tweets, media_tweets), user.profile_bio (description), user.location, and user.verification. The full old-path → new-path mapping is in the table above. TwitterAPI.io normalizes these fields at the gateway so downstream code never breaks.
Are tweet.legacy fields also gone?
No. tweet.legacy is still present inside SearchTimeline. tweet.legacy.full_text, tweet.legacy.created_at, tweet.legacy.favorite_count, tweet.legacy.retweet_count, and tweet.legacy.entities are all still live at the same paths. Only the author-side user.legacy object was removed and split. If your parser crashes on tweet.legacy, the problem is a different endpoint change — not this one.
Why are my twscrape or agent-twitter-client accounts getting suspended for inauthentic behavior?
Self-hosted libraries that retried failed SearchTimeline calls with logged-in session cookies (auth_token / ct0) in a tight loop on 2026-11-21 triggered X's automated anti-automation sweep. The sweep flags accounts whose session shows rapid, patterned failure-retry behavior, especially behind consumer-residential egress. Burner accounts were locked behind Arkose challenges or terminated for 'inauthentic behavior.' The safe path is a managed API that never needs your cookies — one X doesn't see as an authenticated web user at all.
Does the Official X API Basic tier ($200/mo) solve this?
Yes for stability, but it's a different cost and capability envelope. The Official X API is versioned, documented, and will not break the way an internal Web GraphQL endpoint can. However, Basic is rate-limited and charges per read ($0.005 per post read, 3M reads/month cap under current public pricing), so for high-volume search workloads the per-read cost is approximately 33x TwitterAPI.io's $0.00015/tweet rate. The right choice depends on volume and your tolerance for build vs. buy.
Does TwitterAPI.io require me to provide my own X cookies or accounts?
No. You never need X accounts, cookies, auth_token values, ct0 values, or residential proxies. Sign up at twitterapi.io/dashboard for an API key (free tier: up to $1 of free credits, one per person or network, for accounts that pass the automatic bot check). Query real-time Latest or Top search results immediately. Failed (non-200) requests are billed at $0.
How does TwitterAPI.io keep working through these rotations?
We absorb upstream changes at the gateway layer. When X rotates SearchTimeline (as on 2026-11-21) or splits user.legacy into sub-objects, our ingest layer re-targets the new operation hash, re-synthesizes the x-client-transaction-id header against the current web bundle, and projects the response into a stable normalized shape (author.userName, author.followers, tweet.text, tweet.createdAt, etc.). Customers' code reads the same fields from the same paths it did before the incident. The 2026-11-21 event produced 0 customer-facing shape changes.
Is this likely to happen again?
Yes. X's internal Web GraphQL has rotated the SearchTimeline queryId multiple times in the past 12 months, and each rotation has broken the open-source libraries that call it directly. Rotations typically coincide with X Web client bundle releases, so they are not scheduled on a cadence you can reliably pre-empt without maintaining the full reverse-engineering stack. A managed gateway is specifically the architecture that insulates application code from this recurring cost.
Can I use this field mapping without signing up for TwitterAPI.io?
Yes — the mapping table and the defensive Python / TypeScript helper above are free to copy and MIT-equivalent-safe to use in your own code. They will work against the pre- and post-2026-11-21 shapes as long as X keeps serving one of the two. If you want to stop maintaining this layer yourself, the managed endpoint is one paragraph below.
External references & verification sources
Everything stated in this post is independently verifiable from the following primary sources. Where we describe an error signature or a payload field path, you can reproduce it against the upstream repositories below. The external links use rel="nofollow" per our citation policy and open in a new tab.
Broken open-source libraries (primary observation sources)
- twscrape (Python)
See the issues and recent commits tabs for the maintainer's response to the 2026-11-21 break.
- twikit (Python)
See the issues and recent commits tabs for the maintainer's response to the 2026-11-21 break.
- Rettiwt-API (TypeScript)
See the issues and recent commits tabs for the maintainer's response to the 2026-11-21 break.
- agent-twitter-client (TypeScript)
See the issues and recent commits tabs for the maintainer's response to the 2026-11-21 break.
- RSSHub (TypeScript)
See the issues and recent commits tabs for the maintainer's response to the 2026-11-21 break.
X's own documentation
- Official X Developer Platform — API tiers
Pricing and endpoint coverage of the officially supported API ($200 Basic / $5,000+ Enterprise). The internal Web GraphQL rotated on 2026-11-21 is NOT this surface.
- GraphQL — the query language (spec.graphql.org)
Background reading for parsers that need to track upstream schema shape changes. X's internal Web GraphQL is non-standard in several places, but the spec is still useful context.
TwitterAPI.io — normalized managed alternative
- Advanced search endpoint documentation
Request shape and response contract. Stable across upstream rotations.
- Machine-readable pricing
Same prices as /pricing but versioned and parseable by agents and procurement bots.
- Charging rules (when $0 applies on failures)
Failed (non-200) calls cost $0; empty but successful calls bill the 15-credit minimum.
- Hosted MCP server for Claude / Cursor / ChatGPT
Same search endpoints exposed as MCP tools, same normalized shape.
Stop rewriting parsers every time X ships a Web GraphQL update.
TwitterAPI.io normalizes every endpoint into a stable, backward-compatible JSON contract. author.userName, author.followers, tweet.text, and friends never change — regardless of what X's internal Web GraphQL does next. Failed calls stay at $0; successful calls bill at $0.15 per 1,000 tweets.
Related reading: Twitter Search API — complete guide · Twitter API v2 vs. alternatives · Official X API breakdown
Document version: 2026-11-22 rev 3 · Last verified against live upstream: 2026-11-22 03:30 UTC · Author: TwitterAPI.io Engineering · Contact: support@twitterapi.io