Search tweets
The tweets of a search on X (Twitter), 20 a page, with their text, counts, media and author, read with your connected X account.
x/tweets/search20 credits a callv1.1.0When to use it
You want tweets about a subject, from an account, in a language or between two dates: pass the search as you would type it in X's search box, operators included (from:nasa since:2026-11-01 lang:en min_faves:100). tab is the page's own: top (X's selection, the default) or latest (newest first). Follow next unchanged for more. It needs one of your X accounts connected (POST /v2/accounts), and X counts each account's searches: about 50 for 15 minutes. A search ends on a page without a tweet: there are no more.
Try it
The options on the left write the call; the answer on the right is the contract's example. With your API key, the same call returns live data.
curl https://api.lobstr.io/v2/run \ -H "Authorization: Bearer $LOBSTR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "source": "x", "operation": "tweets/search", "options": { "query": "from:nasa since:2026-11-01", "tab": "latest" } }'
An example answer, from the contract. Run it on your own input with your API key.
{ "object": "run", "id": "run_yubtrl4sw24qv3e45qnqfhdnba", "livemode": true, "source": "x", "operation": "tweets/search", "version": "1.1.0", "schema_url": "https://api.lobstr.io/v2/catalog/x/tweets/search", "options": { "query": "from:nasa since:2026-11-01", "tab": "latest" }, "fields": null, "status": "succeeded", "count": 1, "has_more": true, "next": { "source": "x", "operation": "tweets/search", "options": { "query": "from:nasa since:2026-11-01", "tab": "latest", "cursor": "gAAAAABpNWd0x2kQ8vZr3TfYc1LmRb7uHsE9wA4jXoKqDn6yPiGt5" } }, "cost": { "credits": 20 }, "results": [ { "object": "tweet", "id": "2122000000000000001", "position": 1, "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/search?q=from%3Anasa%20since%3A2026-11-01&src=typed_query&f=live", "observed_at": "2026-11-16T15:00:00Z" } ] }
Options
querystringrequiredtab"top" | "latest"Default topaccountstringcursorstringnext in an answer, as it is: opaque, and only for the search it was given with (otherwise invalid_cursor). Leave it out to start at the first page.Record
Each record of results, in the envelope every call returns (Run an operation).
objectstringidstringpositionintegerurlstringtextstringurls and media.languagestringcreated_atdatereply_countintegerretweet_countintegerquote_countintegerlike_countintegerbookmark_countintegerview_countintegerauthor.idstringauthor.handlestringauthor.namestringauthor.urlstringauthor.descriptionstringauthor.description_languagestringauthor.description_urlslistauthor.locationstringauthor.website_urlstringauthor.created_atdateauthor.follower_countintegerauthor.following_countintegerauthor.tweet_countintegerauthor.media_countintegerauthor.like_countintegerauthor.is_blue_verifiedbooleanauthor.is_verifiedbooleanauthor.verified_typestringauthor.is_protectedbooleanauthor.is_possibly_sensitivebooleanauthor.professional.typestringauthor.professional.categorieslistauthor.avatar_urlstringauthor.banner_urlstringauthor.avatar_shapestringauthor.pinned_tweet_idslistauthor.affiliation.namestringauthor.affiliation.urlstringauthor.affiliation.badge_urlstringauthor.affiliation.typestringin_reply_to.tweet_idstringin_reply_to.user_idstringin_reply_to.handlestringis_quotebooleanquoted_tweetobjectretweeted_tweetobjecturlslisthashtagslistsymbolslistmentionslistmedialistcard.typestringcard.urlstringcard.titlestringcard.descriptionstringcard.domainstringcard.image_urlstringarticle.idstringarticle.titlestringarticle.preview_textstringarticle.cover_urlstringarticle.published_atdatearticle.modified_atdateplace.idstringplace.namestringplace.full_namestringplace.typestringplace.countrystringplace.country_codestringplace.bounding_boxlistposted_withstringis_paid_promotionbooleanhas_ai_generated_mediabooleanis_possibly_sensitivebooleanis_longbooleanedit.tweet_idslistedit.editable_untildateedit.edits_remainingintegerids.tweet_idstringids.conversation_idstringids.author_idstringids.quoted_tweet_idstringsource_urlstringobserved_atdateErrors
Its own, besides those of every call (Errors). A failed call is free.
| Code | Status | What it means |
|---|---|---|
invalid_query | 422 | Pass the search as you would type it in X's search box; tab is top or latest. |
account_required | 422 | You have no connected X account. Connect one with POST /v2/accounts {"site": "x", "cookies": ..., "country": "FR"}: the cookies of a browser where you are logged in to x.com, and the country you use the account from (https://docs.lobstr.io/accounts). |
account_rate_limited | 429 | This X account cannot search right now: it pauses a couple of seconds between two pages, and X counts each account's searches (about 50 for 15 minutes). retry_after says when it can search again, in seconds. Retrying before then gets this same answer: nothing is queued. Retryable. |
account_unusable | 409 | 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 | X did not answer properly; retry later (not charged). Retryable. |
unexpected_answer | 424 | X answered in a shape we do not read yet; we are told and fix it (not charged). |
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. What a credit costs on each plan: Credits and pricing.
Each connected account makes one call every 2 seconds, plus 0 to 2 seconds; a busy account answers at once with account_rate_limited and retry_after.
Changelog
1.1.02026-11-17place, 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.02026-11-16