# X (Twitter): List a profile's tweets

`x/tweets/list` · version 1.1.0 · pilot · 20 credits a call

The tweets of a profile on X (Twitter), tab by tab (posts, replies, reposts, videos, photos), newest first, 20 or so a page, with their text, counts, media and author, read with your connected X account.

Categories: Social media

## When to use

You want what an account posts on X: pass its handle (nasa, @nasa) or its profile's address. `tab` is the profile's own: posts (the default: its tweets, its threads as their tweets one by one), replies (its replies, each with the tweet it answers, which is another account's: `author` says whose a tweet is), reposts (the tweets it reposted, each with the tweet repeated in `retweeted_tweet`), videos or photos (the two lists of its Media tab: its tweets with a video, or with a photo, ten or so a page). Follow `next` unchanged for older tweets. It needs one of your X accounts connected (POST /v2/accounts), and X counts each account's requests: about 250 pages of posts, or 50 of any other tab, for 15 minutes. For tweets about a subject, or an account's tweets between two dates, use x/tweets/search.

## Call

```bash
curl https://api.lobstr.io/v2/run \
  -H "Authorization: Bearer $LOBSTR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"source": "x", "operation": "tweets/list", "options": {"profile": "nasa"}}'
```

The answer's `next` is the whole call for the following page: send it as it is. `null` on the last page.

Beside `options`, the call takes:

| Parameter | Type | Description |
|---|---|---|
| `fields` | array of string | The record fields to keep, by path (`title`, `address.city`); `object`, `id` and `position` always come. Left out: every field. |
| `limit` | integer | Only the first N records of this call (1 to 1000), in the call's order; the call costs the same, and `next` keeps the limit. Left out: every record. |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `profile` | string | yes |  | The profile: its handle, with or without the @ (nasa, @nasa), or its address on x.com (https://x.com/nasa). Not its display name. |
| `tab` | `posts`, `replies`, `reposts`, `videos`, `photos` |  | `"posts"` | The tab of the profile's page: posts, replies, reposts, or one of the two lists of its Media tab, videos or photos. |
| `account` | string |  |  | The connected X account to read with (GET /v2/accounts). Left out, the platform takes the first of your X accounts with a free slot. |
| `cursor` | string |  |  | Where to go on, from `next` in an answer, as it is: opaque, and only for the profile and tab it was given with (otherwise `invalid_cursor`). Leave it out to start at the newest tweets. |

## Record

Each item of `results`. Every field is always present, `null` when the site gives nothing.

| Field | Type | Description |
|---|---|---|
| `object` | `"tweet"` |  |
| `id` | string | The tweet's id. |
| `position` | integer | Its rank in the profile's tab, across pages. |
| `is_pinned` | boolean | Whether the profile pinned it at the top of its Posts tab (the page writes Pinned above it). |
| `url` | string (uri) | The tweet on x.com. |
| `text` | string | null | The whole text, a long tweet's included (is_long). Links are X's short ones (t.co), given in full in `urls` and `media`. |
| `language` | string | null | The language X detected: ISO 639-1, or X's own codes (und, zxx, qme...). |
| `created_at` | string | null (date-time) | When it was posted, UTC. |
| `reply_count` | integer | null |  |
| `retweet_count` | integer | null | Reposts. |
| `quote_count` | integer | null |  |
| `like_count` | integer | null |  |
| `bookmark_count` | integer | null |  |
| `view_count` | integer | null | Null when X shows no view count for it. |
| `author` | object | null |  |
| `author.id` | string | The account's id. |
| `author.handle` | string | null | Its @handle, without the @. |
| `author.name` | string | null |  |
| `author.url` | string | null (uri) |  |
| `author.description` | string | null | The bio. |
| `author.description_language` | string | null |  |
| `author.description_urls` | array | The links of the bio |
| `author.location` | string | null | As the account wrote it. |
| `author.website_url` | string | null | The profile's link, in full. |
| `author.created_at` | string | null (date-time) |  |
| `author.follower_count` | integer | null |  |
| `author.following_count` | integer | null |  |
| `author.tweet_count` | integer | null |  |
| `author.media_count` | integer | null |  |
| `author.like_count` | integer | null | The tweets the account liked. |
| `author.is_blue_verified` | boolean | null | The blue check of a paying subscriber. |
| `author.is_verified` | boolean | null | X's earlier verification. |
| `author.verified_type` | string | null | business or government, when X says so. |
| `author.is_protected` | boolean | null |  |
| `author.is_possibly_sensitive` | boolean | null |  |
| `author.professional` | object | null |  |
| `author.professional.type` | string | null | business or creator. |
| `author.professional.categories` | array |  |
| `author.avatar_url` | string | null |  |
| `author.banner_url` | string | null |  |
| `author.avatar_shape` | string | null | circle, square (organizations), hexagon. |
| `author.pinned_tweet_ids` | array of string |  |
| `author.affiliation` | object | null | The organization whose badge the account carries next to its name; null without one. |
| `author.affiliation.name` | string | null | The organization's name on the badge. |
| `author.affiliation.url` | string | null | The organization's profile, as X links it. |
| `author.affiliation.badge_url` | string | null | The badge's image. |
| `author.affiliation.type` | string | null | business_label on every badge seen. |
| `in_reply_to` | object | null | The tweet it replies to; null when it is not a reply. |
| `in_reply_to.tweet_id` | string | null |  |
| `in_reply_to.user_id` | string | null |  |
| `in_reply_to.handle` | string | null |  |
| `is_quote` | boolean | null |  |
| `quoted_tweet` | object | null | The tweet it quotes, with a tweet's fields but position, quoted_tweet, retweeted_tweet, source_url and observed_at. Null when it quotes none, or one X no longer shows (ids.quoted_tweet_id still says which). |
| `retweeted_tweet` | object | null | The tweet it reposts, with the same fields as quoted_tweet. |
| `urls` | array |  |
| `urls[].url` | string | null | The link in full. |
| `urls[].display` | string | null | As the page shows it. |
| `urls[].short_url` | string | null | X's t.co link, as it stands in the text. |
| `hashtags` | array | Without the #. |
| `symbols` | array | Cashtags, without the $. |
| `mentions` | array |  |
| `mentions[].id` | string | null |  |
| `mentions[].handle` | string | null |  |
| `mentions[].name` | string | null |  |
| `media` | array |  |
| `media[].id` | string | null |  |
| `media[].type` | string | null | photo, video or animated_gif. |
| `media[].url` | string | null | The image, or a video's poster. |
| `media[].page_url` | string | null |  |
| `media[].width` | integer | null |  |
| `media[].height` | integer | null |  |
| `media[].alt_text` | string | null |  |
| `media[].duration_ms` | integer | null |  |
| `media[].video_url` | string | null | The video's file of the highest bitrate. |
| `media[].view_count` | integer | null |  |
| `card` | object | null | The preview X draws under a tweet for a link, a poll or a player. |
| `card.type` | string | null | X's name of the card: summary, summary_large_image, player... |
| `card.url` | string | null |  |
| `card.title` | string | null |  |
| `card.description` | string | null |  |
| `card.domain` | string | null |  |
| `card.image_url` | string | null |  |
| `article` | object | null | An X Article attached to the tweet (its title and preview, not its text). |
| `article.id` | string | null |  |
| `article.title` | string | null |  |
| `article.preview_text` | string | null |  |
| `article.cover_url` | string | null |  |
| `article.published_at` | string | null (date-time) |  |
| `article.modified_at` | string | null (date-time) |  |
| `place` | object | null | The place its author tagged it with (Ozuoba, Nigeria); null without one, which is most tweets. X gives the place and the box around it, never the point it was posted from. |
| `place.id` | string | null | X's id of the place. |
| `place.name` | string | null |  |
| `place.full_name` | string | null | The name with its region or country, as the page writes it. |
| `place.type` | string | null | city, admin, country, neighborhood, poi. |
| `place.country` | string | null |  |
| `place.country_code` | string | null | Two letters. |
| `place.bounding_box` | array | The corners of the box around the place, each longitude then latitude. |
| `posted_with` | string | null | The app it was posted with, when X says it: Twitter Web App. |
| `is_paid_promotion` | boolean | null | The author's own disclosure of a paid partnership. |
| `has_ai_generated_media` | boolean | null | X's label of media made with AI. |
| `is_possibly_sensitive` | boolean | null |  |
| `is_long` | boolean | A tweet longer than 280 characters; text holds it whole. |
| `edit` | object | null |  |
| `edit.tweet_ids` | array of string | Its versions, the first to the last. |
| `edit.editable_until` | string | null (date-time) |  |
| `edit.edits_remaining` | integer | null |  |
| `ids` | object |  |
| `ids.tweet_id` | string |  |
| `ids.conversation_id` | string | null | The first tweet of its thread. |
| `ids.author_id` | string | null |  |
| `ids.quoted_tweet_id` | string | null |  |
| `source_url` | string (uri) | The profile's tab on x.com. |
| `observed_at` | string (date-time) | When it was read, UTC. |

Example:

```json
{
  "object": "tweet",
  "id": "2122000000000000001",
  "position": 1,
  "is_pinned": false,
  "url": "https://x.com/NASA/status/2122000000000000001",
  "text": "Liftoff of the resupply mission to the International Space Station. https://t.co/abc123",
  "language": "en",
  "created_at": "2026-11-15T18:42:10Z",
  "reply_count": 312,
  "retweet_count": 1840,
  "quote_count": 96,
  "like_count": 12950,
  "bookmark_count": 410,
  "view_count": 1204500,
  "author": {
    "id": "11348282",
    "handle": "NASA",
    "name": "NASA",
    "url": "https://x.com/NASA",
    "description": "Exploring the secrets of the universe for the benefit of all.",
    "description_language": "en",
    "description_urls": [],
    "location": "Pale Blue Dot",
    "website_url": "https://www.nasa.gov/",
    "created_at": "2007-12-19T20:20:32Z",
    "follower_count": 86000000,
    "following_count": 170,
    "tweet_count": 73000,
    "media_count": 28000,
    "like_count": 16000,
    "is_blue_verified": true,
    "is_verified": false,
    "verified_type": "government",
    "is_protected": false,
    "is_possibly_sensitive": false,
    "professional": null,
    "avatar_url": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB_normal.jpg",
    "banner_url": "https://pbs.twimg.com/profile_banners/11348282/1763000000",
    "avatar_shape": "square",
    "pinned_tweet_ids": [],
    "affiliation": null
  },
  "in_reply_to": null,
  "is_quote": false,
  "quoted_tweet": null,
  "retweeted_tweet": null,
  "urls": [
    {
      "url": "https://www.nasa.gov/live",
      "display": "nasa.gov/live",
      "short_url": "https://t.co/abc123"
    }
  ],
  "hashtags": [],
  "symbols": [],
  "mentions": [],
  "media": [],
  "card": null,
  "article": null,
  "place": null,
  "posted_with": null,
  "is_paid_promotion": null,
  "has_ai_generated_media": null,
  "is_possibly_sensitive": false,
  "is_long": false,
  "edit": {
    "tweet_ids": [
      "2122000000000000001"
    ],
    "editable_until": "2026-11-15T19:42:10Z",
    "edits_remaining": 5
  },
  "ids": {
    "tweet_id": "2122000000000000001",
    "conversation_id": "2122000000000000001",
    "author_id": "11348282",
    "quoted_tweet_id": null
  },
  "source_url": "https://x.com/nasa",
  "observed_at": "2026-11-16T15:00:00Z"
}
```

## Price

20 credits per call that returns tweets, a short last page included. An empty answer, a failed call and a busy account are free.

## Errors

| Code | Status | Retry | Message |
|---|---|---|---|
| `invalid_profile` | 422 | no | Pass a profile's handle (nasa, @nasa) or its address (https://x.com/nasa); tab is posts, replies, reposts, videos or photos. |
| `profile_not_found` | 404 | no | X has no profile with this handle (not charged). |
| `profile_unavailable` | 404 | no | X does not show this profile, suspended or withheld (not charged). |
| `profile_protected` | 403 | no | This profile's posts are protected: X shows them to its followers only, and your connected X account does not follow it (not charged). |
| `account_required` | 422 | no | You have no connected X account. Connect one with POST /v2/accounts {"site": "x", "cookies": ...}: the cookies of a browser where you are logged in to x.com (https://docs.lobstr.io/accounts). |
| `account_rate_limited` | 429 | yes | This X account cannot read a profile right now: it pauses a couple of seconds between two pages, and X counts each account's requests (about 250 pages of posts, 50 of any other tab, for 15 minutes). `retry_after` says when it can again, in seconds. Retrying before then gets this same answer: nothing is queued. |
| `account_unusable` | 409 | no | X logged this account out, or locked it. Open x.com in the browser the account comes from, then connect it again with POST /v2/accounts and fresh cookies (the same account keeps its id). |
| `site_unavailable` | 503 | yes | X did not answer properly; retry later (not charged). |
| `unexpected_answer` | 424 | no | X answered in a shape we do not read yet; we are told and fix it (not charged). |
| `missing_api_key` | 401 | no | No API key: send it as `Authorization: Bearer <key>`. |
| `invalid_api_key` | 401 | no | The key is not valid, or not anymore. |
| `insufficient_credits` | 402 | no | The call costs more credits than are left. |
| `unknown_operation` | 404 | no | No such source and operation in the catalog. |
| `timeout` | 408 | yes | The call did not finish within its deadline (not charged). |
| `invalid_body` | 422 | no | The body is not a call: source, operation, options. |
| `invalid_options` | 422 | no | An option is missing or out of its contract; `param` names it. |
| `invalid_idempotency_key` | 400 | no | The Idempotency-Key header is not printable ASCII, or too long. |
| `concurrency_limit` | 429 | yes | The plan's calls at a time are all in progress (Free 1, Starter 2, Pro 10, Team 50); retry when one has finished (not charged, never queued). |
| `service_busy` | 503 | yes | Too many calls at once on the account; retry in a few seconds. |
| `balance_unavailable` | 503 | yes | The balance could not be read; retry in a few seconds. |

## Changelog

- **1.1.0** (2026-11-17): Two more fields, both null on most tweets: `place`, the place a tweet's author tagged it with, and `author.affiliation`, the organization whose badge the author carries next to its name. `author.website_url` is null, no longer an empty string, when the profile has no link.
- **1.0.0** (2026-11-17): First version on the API v2, in place of the v1 Twitter User Tweets Scraper: a profile by its handle or its address, every tab of its page (posts, replies, reposts, videos, photos), about 20 tweets a page with their counts, media, author, quoted tweet and edits, read with your own connected X account.

Schema: https://api.lobstr.io/v2/catalog/x/tweets/list · All operations: https://api.lobstr.io/v2/catalog.md
