Compatibility

Migrate common official X API reads with familiar paths.

/2 is the focused compatibility layer for existing read integrations. It keeps official-style paths, query names, and response envelopes for the users, tweets, search, and lists surface xfetch can honor accurately. It does not cover writes, media, streaming, trends, or communities. New integrations should start at /v1 for workflow APIs, enriched reads, trend and community reads, and credits in meta.credits.

What /2 covers

xfetch /2 exposes 14 official-style read endpoints across users, tweets, search, and lists. Each maps 1:1 to a /v1 Basic Reads endpoint; see the mapping table on the API reference for /v1 parameter detail. For trends, community discovery, and community timelines, use /v1.

Users

/2 path	Capability	→ /v1
`GET /2/users/by/username/:username`	User by username	`GET /v1/users/by-username/:username`
`GET /2/users/:id`	User by id	`GET /v1/users/:id`
`GET /2/users?ids=...`	Users by ids	`GET /v1/users?ids=...`
`GET /2/users/:id/tweets`	User tweets	`GET /v1/users/:id/tweets`
`GET /2/users/:id/followers`	Followers	`GET /v1/users/:id/followers?mode=ids`
`GET /2/users/:id/following`	Following	`GET /v1/users/:id/following?mode=ids`

Tweets

/2 path	Capability	→ /v1
`GET /2/tweets/:id`	Tweet by id	`GET /v1/tweets/:id`
`GET /2/tweets?ids=...`	Tweets by ids	`GET /v1/tweets?ids=...`
`GET /2/tweets/:id/quote_tweets`	Quote tweets	`GET /v1/tweets/:id/quotes`
`GET /2/tweets/:id/retweeted_by`	Retweeters	`GET /v1/tweets/:id/retweeters`

Search

/2 path	Capability	→ /v1
`GET /2/tweets/search/recent`	Recent search	`GET /v1/search/recent`

Lists

/2 path	Capability	→ /v1
`GET /2/lists/:id/tweets`	List tweets	`GET /v1/lists/:id/tweets`
`GET /2/lists/:id/members`	List members	`GET /v1/lists/:id/members`
`GET /2/lists/:id/followers`	List subscribers/followers	`GET /v1/lists/:id/subscribers`

What /2 does not cover

The official X API surface is larger than xfetch /2. The items below are deliberately not exposed in this compatibility layer.

Capability	Status under /2
Trends and communities	Not exposed under /2. Use /v1/trends, /v1/communities/search, or /v1/communities/:id.
Media	/2 does not expose tweet media. A media-bearing tweet still returns text, metrics, entities, and URLs but no attachments.media_keys or includes.media. Use /v1 media reads when attachments matter.
Broad expansions	Only expansions=author_id is honored, and only on tweet-returning endpoints. Other expansions, media.fields, place.fields, and poll.fields are not advertised as compatible.
Writes	Posting, liking, reposting, following, and DMs are not exposed.
Authenticated-user endpoints	Endpoints based on the caller's identity (such as /2/users/me) are not implemented.
Official streaming APIs	Filtered stream, sampled stream, and replay are not supported under /2. Dashboard-configured account monitor webhooks are separate from this compatibility layer.
Compliance and account-activity APIs	Not exposed.
Full edit history	edit_history_tweet_ids returns only the current version id; the historical chain is not exposed.

Need richer joins, trends, communities, or media-bearing reads? See /v1 workflows and read endpoints. Writes remain outside the launch product.

How /2 behaves differently

Even where /2 keeps official-style paths, behavior is intentionally narrower than the full official API. Plan for these differences before migrating.

Aspect	How /2 does it
Credit metadata location	Response headers `x-request-id`, `x-credits-charged`, and `x-credits-remaining`. `/v1` instead returns credits in `meta.credits`.
Pagination	Requests accept opaque `pagination_token` or `next_token`; responses return `meta.next_token`. Tokens are opaque and must not be parsed or constructed by clients.
max_results	Supported on paginated `/2` collection endpoints using endpoint-specific official-style ranges. xfetch returns at most that many primary items from the provider page and charges only for returned items.
expansions=author_id	Honored on tweet endpoints when the same response contains author objects. `includes.users` is built from those embedded authors; xfetch does not make extra fetches or fabricate missing authors. Non-tweet endpoints reject the parameter instead of accepting a no-op.
tweet.fields / user.fields	Honored over the official-shaped tweet and user objects xfetch returns. Unselected fields are omitted; required base fields such as `id` stay present.
edit_history_tweet_ids	Returned as `[current_id]` only. Full edit history is not exposed.
Media	Not exposed under `/2`. A media-bearing tweet still returns text, metrics, entities, and URLs but no `attachments.media_keys` or `includes.media`.
Errors	Public error envelope with stable codes: `invalid_request`, `invalid_api_key` / `revoked_api_key`, `insufficient_credits`, `endpoint_not_found`, `rate_limited`, `internal_error`, `service_unavailable`. No upstream provider names or raw error strings. Batch user/tweet lookups return successful data plus an official-style `errors` array when some requested IDs are not returned.

Migration examples

Three examples cover single-object reads, paginated collections, and the supported expansion. The response body stays official-style; request IDs and credit details are returned in headers. All samples use $XFETCH_API_KEY as the bearer token placeholder so they are safe to screen-share.

A · Tweet by ID

GET /2/tweets/2055734812669865997
Authorization: Bearer $XFETCH_API_KEY

{
  "data": {
    "id": "2055734812669865997",
    "text": "hello world",
    "edit_history_tweet_ids": ["2055734812669865997"],
    "author_id": "44196397",
    "created_at": "2024-01-15T18:30:00.000Z",
    "lang": "en",
    "public_metrics": {
      "retweet_count": 12,
      "reply_count": 3,
      "like_count": 88,
      "quote_count": 1,
      "bookmark_count": 5
    },
    "entities": { "hashtags": [], "urls": [], "mentions": [] }
  }
}

B · Recent search

GET /2/tweets/search/recent?query=from%3Ajack&max_results=20
Authorization: Bearer $XFETCH_API_KEY

{
  "data": [
    {
      "id": "2055734812669865997",
      "text": "hello world",
      "author_id": "44196397",
      "created_at": "2024-01-15T18:30:00.000Z",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 3,
        "like_count": 88,
        "quote_count": 1,
        "bookmark_count": 5
      },
      "entities": { "hashtags": [], "urls": [], "mentions": [] }
    }
  ],
  "meta": { "result_count": 1, "next_token": "b26v89c19zqg8o3..." }
}

Pagination is via opaque next_token. Pass it back as pagination_token=... on the next call. Tokens are opaque and must not be parsed.

C · expansions=author_id

GET /2/tweets/2055734812669865997?expansions=author_id
Authorization: Bearer $XFETCH_API_KEY

{
  "data": {
    "id": "2055734812669865997",
    "text": "hello world",
    "author_id": "44196397"
  },
  "includes": {
    "users": [
      {
        "id": "44196397",
        "name": "Example",
        "username": "example",
        "public_metrics": {
          "followers_count": 1000,
          "following_count": 200,
          "tweet_count": 5000
        }
      }
    ]
  }
}

includes.users is populated only from author objects already present in the same response. Non-tweet endpoints reject the parameter; if a tweet response does not carry an author object, xfetch does not fabricate one.

Try it with your own key.

Sign in with Google to mint a key and call /2 against your own credits. Free signups receive 1,000 credits; failed validation, auth failures, insufficient credits, rate limits, and service-side failures are not charged.