Skip to main content
The Ruby SDK is for Ruby 3.2+ applications. Use it for typed REST access, retries, Yard docs, RBS, RBI, and connection pooling. Use this page when Ruby code must search tweets. That code can be a Ruby app, Rails job, or Sidekiq worker. Use the page too for tweet exports to CSV, JSON Lines, or XLSX. The code can also export followers, upload media, send DMs, or monitor tweets. It can load records into a warehouse, CRM, queue, or agent.

Install

Or add it to your Gemfile.

Authenticate

Basic example

Search tweets and write durable JSON Lines handoff rows.

Ruby SDK workflows

Tweet replies workflow to CSV, JSON, or XLSX

Use this workflow when Ruby code needs every reply under one tweet. That code can be a Ruby app, Rails job, Sidekiq worker, or agent tool. The replies can come as a saved extraction or a JSON Lines handoff. They can also come as a CSV, JSON, or XLSX file export. Reuse the polling, JSON Lines pagination, and export structure from the follower workflow. Only the tool type, target field, and filenames change.
reply_extractor requires target_tweet_id. client.extractions.retrieve returns results, has_more, and next_cursor. The shared pagination loop passes next_cursor back as cursor. Use xquik-replies.jsonl for queue replay or warehouse loads, and xquik-replies.json for app ingestion. Use xquik-replies.csv for CRM import and xquik-replies.xlsx for analyst handoff. The export call above takes :csv, :json, or :xlsx as format_ for file handoff. The cost is 1 credit per reply extracted or returned.

Cost, limits & retries

Tweet search costs 1 credit per tweet returned. If credits cannot cover a bounded limit request, the API can return fewer tweets. If credits cover 0 results, it returns 402 insufficient_credits. Xquik rate-limits read calls. 429 responses include Retry-After. The client retries connection errors, timeouts, 408, 409, 429, and 5xx responses by default. Handle the rate limit error with backoff.
Fix 400, 401, 403, 404, or 422 responses before retrying.

Error handling

All SDK errors inherit from 1 class.

400 Bad request

Raises BadRequestError.

401 Unauthenticated

Raises AuthenticationError.

403 Permission denied

Raises PermissionDeniedError.

404 Not found

Raises NotFoundError.

422 Unprocessable entity

Raises UnprocessableEntityError.

429 Rate limited

Raises RateLimitError.

5xx server error

Raises InternalServerError.

Pagination

Paginated responses expose fields such as has_next_page. Pass the endpoint’s cursor fields when requesting more pages.

Webhooks & references