Skip to main content
This guide builds on the Ruby SDK setup, which covers install and authentication.

​
Tweet search workflow to CSV, JSON Lines, or XLSX

Search with client.x.tweets.search, GET /x/tweets/search, and generated XTwitterScraper::X::TweetSearchParams. Save CSV and JSON Lines for Ruby workers, Rails, Sidekiq, agents, warehouses, and replay.
The generated params map directly to the REST endpoint.

q

Ruby keyword q maps to REST q. It holds the required X (Twitter) search query with keywords, handles, hashtags, or operators.

limit

Ruby keyword limit maps to REST limit. Use it as a 1 to 200 upper bound for a bounded pull. If page.has_next_page is true, keep the same q, filters, query_type, and limit. That applies when you continue with page.next_cursor.

cursor

Ruby keyword cursor maps to REST cursor. Pass the opaque cursor from page.next_cursor to request the next page.

since_time

Ruby keyword since_time maps to REST sinceTime. Use it as the ISO 8601 lower time bound.

until_time

Ruby keyword until_time maps to REST untilTime. Use it as the ISO 8601 upper time bound.

query_type

Ruby keyword query_type maps to REST queryType. Use :Latest for chronological results or :Top for engagement-ranked results.

​
Returned data & handoff

client.x.tweets.search returns XTwitterScraper::PaginatedTweets.

page.tweets

JSON field tweets. Contains SearchTweet records with id, text, optional author, and created_at. Records also carry like_count, reply_count, retweet_count, quote_count, bookmark_count, view_count, and is_note_tweet when available.

page.has_next_page

Ruby field page.has_next_page. JSON field has_next_page. Tells your worker whether another page exists.

page.next_cursor

JSON field next_cursor. Store it only when page.has_next_page is true. For bounded pulls that return fewer tweets than limit, pass it back as cursor. Send the same query, filters, query_type, and limit with it.
Project page.tweets into CSV rows for analysts. Project them into JSON Lines rows for queues and data lakes. Store tweet_id, author_username, engagement counts, page_index, page_cursor, next_cursor, and has_next_page in xquik-tweet-search.jsonl. Workers can then resume. Or they can load the same records into XLSX, CRM, warehouse, or agent workflows. For explicit limit pulls, resume with the same query, filters, query_type, and limit. Only cursor changes.

​
Next steps