API reference

Health check

Service liveness plus scraper session pool status (operational | degraded | down).

const res = await fetch(`${BASE}/health`);
const data = await res.json();
console.log(data);

List available API commands

Full list of available commands.

• Also available at GET / and GET /v1/commands
• Also available for API tools at GET /v1/openapi.json

const res = await fetch(`${BASE}/v1`);
const data = await res.json();
console.log(data);

Schema for API tools

Command list in a format API tools understand.

const res = await fetch(`${BASE}/v1/openapi.json`);
const data = await res.json();
console.log(data);

Current account plan and usage

Returns plan limits, remaining RPM/daily/monthly quota, and reset timestamps for the account that owns this API key.

• Counts as one request against your account quota
• Also mirrored on every keyed response via X-RateLimit-* and X-RateLimit-Reset* headers
• Response envelope: { data, meta }

const res = await fetch(`${BASE}/v1/me`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get user profile and stats

Returns profile fields, follower/following counts, statuses, media counts, etc. Lookup by handle or numeric rest id.

• Response envelope: { data, meta } with meta.cached / meta.fetched_at
• Cache-Control: private, max-age=60 (or CACHE_TTL_MS capped); weak ETag from user id + fetched_at; 304 on If-None-Match
• userName takes precedence if both are sent
• data.currentSpace is live (fleets), not from the profile cache. Pass include_space=0 to skip.
• data.currentBroadcast is the live video stream they are hosting, or null. X does not expose watchers. Pass include_broadcast=0 to skip.

const res = await fetch(`${BASE}/v1/user/info?userName=elonmusk&userId=44196397&fresh=1&include_space=1&include_broadcast=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get latest tweets for a user

User timeline with cursor pagination. Tweets include media[] (url, previewUrl, width/height, durationMs, altText, variants[] with contentType/url/bitrate).

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/tweets?userName=elonmusk&limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get tweets and replies for a user

Timeline including the user's replies (UserTweetsAndReplies). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/tweets-and-replies?userName=elonmusk&limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get tweets mentioning a user

Tweets that mention an account (SearchTimeline `@handle -from:handle`). Cursor-paginated. Not the authenticated user's notification inbox.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.
• meta.query is the search string used; equivalent to GET /v1/search/tweets?query=@handle%20-from:handle

const res = await fetch(`${BASE}/v1/user/mentions?userName=elonmusk&product=Latest&limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Search tweets

Latest/Top search over X posts.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/search/tweets?query=solana&product=Latest&limit=5&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Search users

People search over X accounts via SearchTimeline (product=People). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/search/users?query=solana&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get media tweets for a user

Media tab timeline (photos/videos/gifs). Cursor-paginated; tweets include media[] (altText and video variants[]).

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/media?userName=nasa&limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get tweets from an X list

Latest tweets from a public list by numeric list id. Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/list/1539453138322673664/tweets?limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get tweets from an X community

Community timeline (CommunityTweetsTimeline). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/community/1489422448332197888/tweets?ranking=Relevance&limit=20&include_replies=0&include_retweets=1&media_only=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get community metadata

Community name, description, member count, join policy (CommunityQuery).

• Response envelope: { data, meta }

const res = await fetch(`${BASE}/v1/community/1489422448332197888`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get an X Space

Title, state, start time, listener counts, host/admins/speakers, and a listener sample (AudioSpaceById).

• Response envelope: { data, meta }
• state is running | ended | scheduled | canceled | unknown
• listeners[] is a sample; compare listeners.length to listenerCount. Silent listeners are not a complete roster.
• admins = hosts/co-hosts, speakers = on-stage guests

const res = await fetch(`${BASE}/v1/space/1wxWjlvBZynJQ`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get users in an X Space

Hosts, on-stage speakers, and a listener sample for a Space. Filter with role=admins|speakers|listeners|on_stage|all.

• Response envelope: { data, next_cursor, cursor, meta } — snapshot, not cursor-paged
• Each row: id, userName, name, profileImageUrl, isBlueVerified, role, joinedAt*
• meta.listener_sample is true when listeners.length < listenerCount

const res = await fetch(`${BASE}/v1/space/1wxWjlvBZynJQ/users?role=on_stage`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get an X broadcast (live video)

Title, state, host, viewer counts, thumbnail, and start time for a live or replayable video broadcast.

• Response envelope: { data, meta }
• state is running | ended | scheduled | canceled | unknown
• X does not expose a watcher roster — only watchingCount / watchedCount
• host is the account running the stream

const res = await fetch(`${BASE}/v1/broadcast/1nxeLMkBVgYJX`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Trending topics by location

Trending topics for a Yahoo WOEID via X trends/place. 1 = Worldwide. Tweet volumes are what X returns (often null).

• Response envelope: { data, next_cursor, cursor, meta } — next_cursor is always null
• Each trend: name, query, url, tweetVolume
• This is not a tweet-volume time series (X tweets/counts/recent). Use search for that.

const res = await fetch(`${BASE}/v1/trends?woeid=1`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get a tweet by id

Returns a single post with author, media[] (including altText and video variants[]), and engagement counts (likes, replies, retweets, quotes, bookmarks, views).

• Response envelope: { data, meta }
• Cache-Control: private, max-age=60 (or CACHE_TTL_MS capped); weak ETag from tweet id; 304 on If-None-Match

const res = await fetch(`${BASE}/v1/tweet/20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get a tweet by X/Twitter URL

Accepts an x.com or twitter.com status URL (or raw numeric id) and returns the same shape as tweet-by-id.

• Response envelope: { data, meta }
• Cache-Control: private, max-age=60 (or CACHE_TTL_MS capped); weak ETag from tweet id; 304 on If-None-Match

const res = await fetch(`${BASE}/v1/tweet/by-url?url=https%3A%2F%2Fx.com%2Fjack%2Fstatus%2F20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get replies to a tweet

Conversation replies for a post (commenters + engagement). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.
• Parent tweet (when available) is in meta.tweet

const res = await fetch(`${BASE}/v1/tweet/20/replies?limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Get thread context for a tweet

Parent chain (ancestors, oldest first), the focal tweet, and first-page replies from TweetDetail.

• Response envelope: { data, meta } with data.tweet, data.ancestors, data.replies
• Pass meta.next_cursor as ?cursor= to page more replies
• Missing parents are fetched up the inReplyTo chain (bounded)

const res = await fetch(`${BASE}/v1/tweet/20/thread?limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

List users who retweeted a tweet

Retweeters for a post. Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.
• createdAt is the account join date. X does not expose when each user retweeted.

const res = await fetch(`${BASE}/v1/tweet/20/retweeters?limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Like count for a tweet

Returns how many times a post was liked. X does not expose who liked it to these sessions. Same number as favoriteCount on GET /v1/tweet/{id}.

• Response envelope: { data, meta }
• data: { id, likes }

const res = await fetch(`${BASE}/v1/tweet/20/likes`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

List quote tweets of a tweet

Quote posts for a status via search (quoted_tweet_id). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/tweet/20/quotes?limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

List users who quoted a tweet

Unique authors of quote tweets. Cursor-paginated (same cursor as /quotes).

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.
• quotedAt / quotedAtMs / quotedAtIso is when that user posted the quote tweet.

const res = await fetch(`${BASE}/v1/tweet/20/quoters?limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Build an engager pool / pick winners

Pages retweeters, reply authors, and/or quoters into a deduped pool. Optional random winners (TwitterPicker-style). Like identities are not available; use GET /v1/tweet/{id}/likes for the count.

• Response envelope: { data, meta }
• meta.counts has per-type and pool sizes; meta.notes explains skipped like identities
• Without winners, data is the full deduped pool

const res = await fetch(`${BASE}/v1/tweet/20/engagers?types=retweet%2Creply%2Cquote&mode=union&max_pages=3&limit=20&winners=5&seed=42`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Batch fetch tweets by id

Fetch up to 25 tweets in one request. Partial failures return in errors[].

• Response envelope: { data, meta } with meta.errors / meta.max

const res = await fetch(`${BASE}/v1/tweets`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ids": [
      "20",
      "https://x.com/jack/status/20"
    ]
  }),
});
const data = await res.json();
console.log(data);

Batch fetch user profiles

Fetch up to 25 profiles in one request by handle and/or numeric rest id. Partial failures return in errors[].

• Response envelope: { data, meta } with meta.errors / meta.max
• Each user includes currentSpace and currentBroadcast (live fleets lookup) or null

const res = await fetch(`${BASE}/v1/users`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "userNames": [
      "jack"
    ],
    "userIds": [
      "44196397"
    ]
  }),
});
const data = await res.json();
console.log(data);

List followers for a user

Followers of an X account. Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/followers?userName=elonmusk&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

List accounts a user follows

Following list for an X account. Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/following?userName=elonmusk&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

List verified followers for a user

Blue-verified followers only (BlueVerifiedFollowers). Cursor-paginated.

• Response envelope: { data, next_cursor, cursor, meta }
• meta.has_next_page mirrors next_cursor; extra context (user, filters, query) lives in meta
• Pass next_cursor back as ?cursor=. Do not invent or parse cursors
• Posts include createdAt (X date string), createdAtMs (unix ms), and createdAtIso (ISO-8601). On a retweet, createdAt is when it was reposted; retweetedStatus is the original post. Quotes expose quotedStatus the same way.

const res = await fetch(`${BASE}/v1/user/verified-followers?userName=elonmusk&limit=20`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

Check follow relationship between two users

Whether source follows target and vice versa, via X friendships/show. Not scoped to the cookie owner.

• Response envelope: { data, meta }
• data.source.following is true when source follows target
• meta.source_follows_target / meta.target_follows_source mirror those flags

const res = await fetch(`${BASE}/v1/user/relationship?sourceUserName=jack&targetUserName=elonmusk&sourceUserId=12&targetUserId=44196397`, {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
});
const data = await res.json();
console.log(data);