Docs · User tweets

User tweets

An account's tweets and retweets, about 20 per page, with text, media and engagement counts.

1 credit per callFresh within 5 minutesMCP tool: twitter_user_tweets

GEThttps://api.lurkapi.com/v1/twitter/user-tweets

When to use this

Use it to audit what an account posts and how each post does. Retweets are included (the original is in retweeted_tweet); replies aren't, except the account's own threads. On the first page the pinned tweet comes first, with pinned: true.

Ordering. Check ordering. For most accounts it's chronological: newest first, with more pages. For some very large accounts X shows logged-out visitors only a ranked sample instead: about 100 popular tweets from all years, in X's order, with no next page.

Pagination. Pass the response's cursor back as cursor (with the same handle) for older tweets; it's null at the end.

Unknown and suspended accounts return 404 not_found, and so do protected accounts, whose tweets need a login.

Parameters

All parameters go in the query string.

Parameter	Description
`handle` stringrequired	X username, with or without @ (e.g. `NASA`), or the profile URL. Example `NASA`
`cursor` stringoptional	The `cursor` from the previous response, to get older tweets.

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curlJavaScriptPython

JavaScript · reads your key from LURKAPI_KEY

const params = new URLSearchParams({
  handle: "NASA",
});
const res = await fetch(`https://api.lurkapi.com/v1/twitter/user-tweets?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.tweets);

Python · reads your key from LURKAPI_KEY

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/twitter/user-tweets",
    params={
        "handle": "NASA",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=60,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["tweets"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

Show the example response (4 KB)

{
  "success": true,
  "credits_remaining": 999997,
  "credits_charged": 1,
  "tweets": [
    {
      "id": "2104593672624886205",
      "url": "https://x.com/NASA/status/2104593672624886205",
      "text": "How do we respond when we detect an asteroid that could pose a threat to…",
      "created_at": "2026-09-28T15:26:47.000Z",
      "lang": "en",
      "source": "Sprinklr",
      "author": {
        "id": "11348282",
        "handle": "NASA",
        "name": "NASA",
        "avatar": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
        "verified": true,
        "verified_type": "Government",
        "followers": 92377446
      },
      "counts": {
        "likes": 3228,
        "replies": 210,
        "retweets": 538,
        "quotes": 40,
        "bookmarks": 267,
        "views": 676901
      },
      "media": [
        {
          "type": "video",
          "url": "https://pbs.twimg.com/media/HTUEyn0XkAALVB_.png",
          "width": 405,
          "height": 720,
          "duration_ms": 38605,
          "variants": [
            {
              "url": "https://video.twimg.com/amplify_video/2104593621043314689/vid/avc1/608x1…",
              "content_type": "video/mp4",
              "bitrate": 2176000
            },
            {
              "url": "https://video.twimg.com/amplify_video/2104593621043314689/vid/avc1/480x8…",
              "content_type": "video/mp4",
              "bitrate": 950000
            },
            {
              "url": "https://video.twimg.com/amplify_video/2104593621043314689/vid/avc1/320x5…",
              "content_type": "video/mp4",
              "bitrate": 632000
            },
            {
              "url": "https://video.twimg.com/amplify_video/2104593621043314689/pl/iMMWqCJ1OZowER7i.m3u8?tag=16&v=2b3",
              "content_type": "application/x-mpegURL",
              "bitrate": null
            }
          ]
        }
      ],
      "hashtags": [],
      "mentions": [],
      "links": [
        "https://go.nasa.gov/4AUCQ3Z"
      ],
      "reply_to_id": null,
      "reply_to_handle": null,
      "conversation_id": "2104593672624886205",
      "quoted_id": null,
      "possibly_sensitive": false,
      "quoted_tweet": null,
      "retweeted_tweet": null,
      "pinned": true
    },
    {
      "id": "2105014687532212518",
      "url": "https://x.com/NASA/status/2105014687532212518",
      "text": "We're ready for Crew-13 to launch to the @Space_Station! Join us for a p…",
      "created_at": "2026-09-29T19:19:45.000Z",
      "lang": "en",
      "source": "Sprinklr",
      "author": {
        "id": "11348282",
        "handle": "NASA",
        "name": "NASA",
        "avatar": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_400x400.jpg",
        "verified": true,
        "verified_type": "Government",
        "followers": 92377446
      },
      "counts": {
        "likes": 2279,
        "replies": 134,
        "retweets": 283,
        "quotes": 28,
        "bookmarks": 73,
        "views": 827274
      },
      "media": [
        {
          "type": "photo",
          "url": "https://pbs.twimg.com/media/HTaDs_pXwAAzhcG.jpg",
          "width": 1919,
          "height": 894,
          "duration_ms": null,
          "variants": []
        }
      ],
      "hashtags": [],
      "mentions": [
        "Space_Station"
      ],
      "links": [
        "https://go.nasa.gov/4hSzzKG"
      ],
      "reply_to_id": null,
      "reply_to_handle": null,
      "conversation_id": "2105014687532212518",
      "quoted_id": null,
      "possibly_sensitive": false,
      "quoted_tweet": null,
      "retweeted_tweet": null,
      "pinned": false
    }
  ],
  "cursor": "nasa:11348282:DAAHCgABHTeLQPC__-wLAAIAAAATMjEwMjUyMDE2MzIyNDc2MDU0MQgAAwAAAAIAAA",
  "ordering": "chronological"
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Show all 126 fields

Field	Type	Description
success	true	Always true here; errors have `success: false`.
credits_remaining	number	Your balance after this call. On anonymous playground calls: free tries left today.
credits_charged	number	Credits this call cost; 0 on free endpoints. On anonymous playground calls: tries used (1).
tweets	object[]	One page of tweets and retweets, in `ordering` order.
tweets[].id	string	Tweet id, e.g. `2104593672624886205`.
tweets[].url	string	The tweet on x.com.
tweets[].text	string	The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets.
tweets[].created_at	string	When it was posted, ISO 8601.
tweets[].lang	stringnullable	Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.
tweets[].source	stringnullable	The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.
tweets[].author	object	Who posted it.
tweets[].author.id	string	Numeric user id. It stays the same when the handle changes.
tweets[].author.handle	string	Username (handle), without @.
tweets[].author.name	string	Display name.
tweets[].author.avatar	stringnullable	Profile picture URL, 400×400; null if none.
tweets[].author.verified	boolean	Has the blue check (X Premium).
tweets[].author.verified_type	stringnullable	`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.
tweets[].author.followers	numbernullable	Followers when fetched; null when X's main source was busy and the tweet came from its embed data.
tweets[].counts	object	Engagement when fetched. Exact numbers, not rounded.
tweets[].counts.likes	number	Likes.
tweets[].counts.replies	number	Replies.
tweets[].counts.retweets	numbernullable	Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.
tweets[].counts.quotes	numbernullable	Quote posts; null when X's main source was busy and the tweet came from its embed data.
tweets[].counts.bookmarks	numbernullable	Bookmarks; null when X's main source was busy and the tweet came from its embed data.
tweets[].counts.views	numbernullable	Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.
tweets[].media	object[]	Attached photos, videos and GIFs, in order. Empty if none.
tweets[].media[].type	string	`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s).
tweets[].media[].url	string	The image; for videos and GIFs, the poster (thumbnail) image.
tweets[].media[].width	number	Original width in pixels.
tweets[].media[].height	number	Original height in pixels.
tweets[].media[].duration_ms	numbernullable	Video length in milliseconds; null for photos and GIFs.
tweets[].media[].variants	object[]	Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos.
tweets[].media[].variants[].url	string	File URL on video.twimg.com.
tweets[].media[].variants[].content_type	string	`video/mp4`, or `application/x-mpegURL` for the HLS playlist.
tweets[].media[].variants[].bitrate	numbernullable	Bits per second; null for the HLS playlist.
tweets[].hashtags	string[]	Hashtags in the text, without #.
tweets[].mentions	string[]	Usernames @mentioned, including the ones a reply is addressed to.
tweets[].links	string[]	Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included.
tweets[].reply_to_id	stringnullable	Id of the tweet this replies to; null if it isn't a reply.
tweets[].reply_to_handle	stringnullable	Username of the account this replies to; null if it isn't a reply.
tweets[].conversation_id	stringnullable	Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.
tweets[].quoted_id	stringnullable	Id of the tweet this one quotes; null if it isn't a quote.
tweets[].possibly_sensitive	boolean	X marks the media as possibly sensitive.
tweets[].quoted_tweet	objectnullable	The tweet this one quotes (without its own quoted or retweeted tweet); null if none or it's no longer available.
tweets[].quoted_tweet.id	string	Tweet id, e.g. `2104593672624886205`.
tweets[].quoted_tweet.url	string	The tweet on x.com.
tweets[].quoted_tweet.text	string	The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets.
tweets[].quoted_tweet.created_at	string	When it was posted, ISO 8601.
tweets[].quoted_tweet.lang	stringnullable	Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.
tweets[].quoted_tweet.source	stringnullable	The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.
tweets[].quoted_tweet.author	object	Who posted it.
tweets[].quoted_tweet.author.id	string	Numeric user id. It stays the same when the handle changes.
tweets[].quoted_tweet.author.handle	string	Username (handle), without @.
tweets[].quoted_tweet.author.name	string	Display name.
tweets[].quoted_tweet.author.avatar	stringnullable	Profile picture URL, 400×400; null if none.
tweets[].quoted_tweet.author.verified	boolean	Has the blue check (X Premium).
tweets[].quoted_tweet.author.verified_type	stringnullable	`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.
tweets[].quoted_tweet.author.followers	numbernullable	Followers when fetched; null when X's main source was busy and the tweet came from its embed data.
tweets[].quoted_tweet.counts	object	Engagement when fetched. Exact numbers, not rounded.
tweets[].quoted_tweet.counts.likes	number	Likes.
tweets[].quoted_tweet.counts.replies	number	Replies.
tweets[].quoted_tweet.counts.retweets	numbernullable	Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.
tweets[].quoted_tweet.counts.quotes	numbernullable	Quote posts; null when X's main source was busy and the tweet came from its embed data.
tweets[].quoted_tweet.counts.bookmarks	numbernullable	Bookmarks; null when X's main source was busy and the tweet came from its embed data.
tweets[].quoted_tweet.counts.views	numbernullable	Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.
tweets[].quoted_tweet.media	object[]	Attached photos, videos and GIFs, in order. Empty if none.
tweets[].quoted_tweet.media[].type	string	`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s).
tweets[].quoted_tweet.media[].url	string	The image; for videos and GIFs, the poster (thumbnail) image.
tweets[].quoted_tweet.media[].width	number	Original width in pixels.
tweets[].quoted_tweet.media[].height	number	Original height in pixels.
tweets[].quoted_tweet.media[].duration_ms	numbernullable	Video length in milliseconds; null for photos and GIFs.
tweets[].quoted_tweet.media[].variants	object[]	Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos.
tweets[].quoted_tweet.media[].variants[].url	string	File URL on video.twimg.com.
tweets[].quoted_tweet.media[].variants[].content_type	string	`video/mp4`, or `application/x-mpegURL` for the HLS playlist.
tweets[].quoted_tweet.media[].variants[].bitrate	numbernullable	Bits per second; null for the HLS playlist.
tweets[].quoted_tweet.hashtags	string[]	Hashtags in the text, without #.
tweets[].quoted_tweet.mentions	string[]	Usernames @mentioned, including the ones a reply is addressed to.
tweets[].quoted_tweet.links	string[]	Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included.
tweets[].quoted_tweet.reply_to_id	stringnullable	Id of the tweet this replies to; null if it isn't a reply.
tweets[].quoted_tweet.reply_to_handle	stringnullable	Username of the account this replies to; null if it isn't a reply.
tweets[].quoted_tweet.conversation_id	stringnullable	Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.
tweets[].quoted_tweet.quoted_id	stringnullable	Id of the tweet this one quotes; null if it isn't a quote.
tweets[].quoted_tweet.possibly_sensitive	boolean	X marks the media as possibly sensitive.
tweets[].retweeted_tweet	objectnullable	For retweets: the original tweet, with its own text and counts. null for everything else.
tweets[].retweeted_tweet.id	string	Tweet id, e.g. `2104593672624886205`.
tweets[].retweeted_tweet.url	string	The tweet on x.com.
tweets[].retweeted_tweet.text	string	The text as x.com shows it: long posts in full, t.co links expanded, without a reply's leading @mentions or the trailing media link. Empty for media-only tweets.
tweets[].retweeted_tweet.created_at	string	When it was posted, ISO 8601.
tweets[].retweeted_tweet.lang	stringnullable	Language as X detects it, e.g. `en` (`und` when it can't tell); null if unknown.
tweets[].retweeted_tweet.source	stringnullable	The app it was posted from, e.g. `Twitter for iPhone`; null if X doesn't say.
tweets[].retweeted_tweet.author	object	Who posted it.
tweets[].retweeted_tweet.author.id	string	Numeric user id. It stays the same when the handle changes.
tweets[].retweeted_tweet.author.handle	string	Username (handle), without @.
tweets[].retweeted_tweet.author.name	string	Display name.
tweets[].retweeted_tweet.author.avatar	stringnullable	Profile picture URL, 400×400; null if none.
tweets[].retweeted_tweet.author.verified	boolean	Has the blue check (X Premium).
tweets[].retweeted_tweet.author.verified_type	stringnullable	`Business` (gold check, a verified organization) or `Government` (grey check); null otherwise.
tweets[].retweeted_tweet.author.followers	numbernullable	Followers when fetched; null when X's main source was busy and the tweet came from its embed data.
tweets[].retweeted_tweet.counts	object	Engagement when fetched. Exact numbers, not rounded.
tweets[].retweeted_tweet.counts.likes	number	Likes.
tweets[].retweeted_tweet.counts.replies	number	Replies.
tweets[].retweeted_tweet.counts.retweets	numbernullable	Reposts (retweets); null when X's main source was busy and the tweet came from its embed data.
tweets[].retweeted_tweet.counts.quotes	numbernullable	Quote posts; null when X's main source was busy and the tweet came from its embed data.
tweets[].retweeted_tweet.counts.bookmarks	numbernullable	Bookmarks; null when X's main source was busy and the tweet came from its embed data.
tweets[].retweeted_tweet.counts.views	numbernullable	Views; null on tweets from before 2023 (X didn't count them then), and null when X's main source was busy and the tweet came from its embed data.
tweets[].retweeted_tweet.media	object[]	Attached photos, videos and GIFs, in order. Empty if none.
tweets[].retweeted_tweet.media[].type	string	`photo`, `video` or `gif` (X plays GIFs as silent looping MP4s).
tweets[].retweeted_tweet.media[].url	string	The image; for videos and GIFs, the poster (thumbnail) image.
tweets[].retweeted_tweet.media[].width	number	Original width in pixels.
tweets[].retweeted_tweet.media[].height	number	Original height in pixels.
tweets[].retweeted_tweet.media[].duration_ms	numbernullable	Video length in milliseconds; null for photos and GIFs.
tweets[].retweeted_tweet.media[].variants	object[]	Playable files for videos and GIFs: MP4s from highest to lowest bitrate, then the HLS playlist. Empty for photos.
tweets[].retweeted_tweet.media[].variants[].url	string	File URL on video.twimg.com.
tweets[].retweeted_tweet.media[].variants[].content_type	string	`video/mp4`, or `application/x-mpegURL` for the HLS playlist.
tweets[].retweeted_tweet.media[].variants[].bitrate	numbernullable	Bits per second; null for the HLS playlist.
tweets[].retweeted_tweet.hashtags	string[]	Hashtags in the text, without #.
tweets[].retweeted_tweet.mentions	string[]	Usernames @mentioned, including the ones a reply is addressed to.
tweets[].retweeted_tweet.links	string[]	Links in the text, expanded (not t.co). The tweet's own photos and videos aren't included.
tweets[].retweeted_tweet.reply_to_id	stringnullable	Id of the tweet this replies to; null if it isn't a reply.
tweets[].retweeted_tweet.reply_to_handle	stringnullable	Username of the account this replies to; null if it isn't a reply.
tweets[].retweeted_tweet.conversation_id	stringnullable	Id of the thread's first tweet (its own id if it starts one); null if X doesn't say.
tweets[].retweeted_tweet.quoted_id	stringnullable	Id of the tweet this one quotes; null if it isn't a quote.
tweets[].retweeted_tweet.possibly_sensitive	boolean	X marks the media as possibly sensitive.
tweets[].pinned	boolean	The account's pinned tweet, shown first.
cursor	stringnullable	Pass as `cursor` for the next page; null on the last page and for `ranked` results.
ordering	string	`chronological`: newest first, with more pages. `ranked`: X shows logged-out visitors of this very large account only about 100 popular tweets from all years, with no next page.

Pagination

Pass the response's cursor back as cursor, with the other parameters unchanged, for the next page. It's null on the last page. Each page costs 1 credit.

The first five pages, in JavaScript

let cursor = null;
for (let page = 1; page <= 5; page++) {
  const params = new URLSearchParams({ handle: "NASA" });
  if (cursor) params.set("cursor", cursor);
  const res = await fetch(`https://api.lurkapi.com/v1/twitter/user-tweets?${params}`, {
    headers: { "x-api-key": process.env.LURKAPI_KEY },
  });
  const data = await res.json();
  if (!data.success) throw new Error(`${data.code}: ${data.error}`);
  console.log(data.tweets);
  cursor = data.cursor;
  if (!cursor) break; // last page
}

Caching and freshness

Responses are cached for up to 5 minutes, so a repeat call within that window can return the same data. It still costs 1 credit.

Errors

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Status	Code	Meaning
401	`missing_api_key`	No API key. Send it in the `x-api-key` header.
401	`invalid_api_key`	The key is unknown or was revoked.
402	`insufficient_credits`	Not enough credits for this call. Buy a pack or wait for tomorrow's top-up.
404	`not_found`	The endpoint, or the thing you asked for (ad, post, subreddit), doesn't exist. Charged when the platform was checked.
405	`method_not_allowed`	Endpoints take GET with query params.
429	`rate_limited`	Too many calls at once. Wait for the `retry-after` seconds, then retry.
500	`internal_error`	Something broke on our side. Retry; 5xx errors are free.
502	`upstream_error`	The platform didn't give a usable answer. Retry; 5xx errors are free.
503	`upstream_busy`	All our connections to the platform are busy. Retry in a few seconds; 5xx errors are free.
504	`upstream_timeout`	The platform took over 30 seconds to answer. Retry; timeouts are free.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the twitter_user_tweets tool. Ask in plain English, for example:

Ask Claude

Use LurkAPI's twitter_user_tweets with handle "NASA" and summarize what you find.

Claude calls twitter_user_tweets with arguments like these, and each call costs 1 credit:

Tool arguments

{
  "handle": "NASA"
}

Tool results skip nulls and empty lists to save tokens.