How to scrape TikTok Followers with Ruby

A profile's followers, newest first. This tutorial gets it with a short Ruby program and the TikTok Followers API. Each successful call costs 1 credit; errors and not-found answers are free.

1. Get an API key

Sign in to get a key and 100 free credits, no card. Then put the key in an environment variable so it stays out of your code:

export SCRAPEIO_API_KEY="your_key_here"

2. Set up Ruby

Ruby 3; net/http and json are built in

3. Write the code

Save this as scrape.rb.

require "json"
require "net/http"

params = { "handle" => "nike" }

def call(params)
  uri = URI("https://scrapeio.com/v1/tiktok/user/followers")
  uri.query = URI.encode_www_form(params)
  req = Net::HTTP::Get.new(uri)
  req["x-api-key"] = ENV.fetch("SCRAPEIO_API_KEY")
  res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
  raise "HTTP #{res.code}" unless res.code == "200"
  JSON.parse(res.body)["data"]
end

items = []
loop do
  data = call(params)
  items.concat(data["items"] || [])
  break if !data["has_more"] || data["cursor"].to_s.empty? || items.size >= 100
  params["cursor"] = data["cursor"]
end
puts "#{items.size} items"
puts JSON.pretty_generate(items.first(3))

The loop follows data.cursor until data.has_more is false, and stops at 100 items. Each page is one call, so it costs 1 credit.

4. Run it

ruby scrape.rb

The response has the same envelope on every endpoint: success, cached, credits_used, credits_remaining and data. Shared fields such as handle, followers, plays, likes and created_at have the same names on every platform.

Parameters

Name	Type	Description
`handle` (required)	string	TikTok username, with or without @.
`cursor`	string	Cursor from the previous page's data.cursor.

Errors and what you pay

Status	Meaning	Charged
`200`	Success	Yes, unless cached
`400`	A parameter is missing or wrong	No
`401`	The key is missing or invalid	No
`402`	Not enough credits	No
`403`	The account or post is private	No
`404`	Not found on the platform	No
`429`	More than 300 requests a minute	No
`502`	Every source is down; retry shortly	No

Same endpoint in other languages

Python · Node.js · JavaScript · TypeScript · Go · Rust · Java · C# · PHP · Kotlin · Swift · R

Prefer no code?

Connect the MCP server to Claude Code, Cursor or Codex and ask in plain English. The agent uses the tiktok_followers tool for you.

100 free credits, no card. Credits never expire.

Get API key