Ruby · Code recipe

Run a Lighthouse audit in Ruby

Score any page for performance, accessibility, best practices and SEO, in Ruby 3.1+ with Net::HTTP from the standard library. Every program on this page runs as it stands — each one was run against a stub of the API before it was published.

By Roger Campos · Last updated: September 2026

TL;DR

To run a Lighthouse audit in Ruby, POST a URL and a device to https://urlpipe.dev/lighthouse and read the JSON with JSON.parse: four category scores from 0 to 1 and the lab metrics, LCP, CLS and TBT among them. An audit takes around 15 seconds, so the async variant with a webhook suits production. It costs 2 credits.

Start free See the API

Free plan, no credit card. 1,000 credits a month.

One POST to /lighthouse runs a real Lighthouse audit in Chrome and answers with the four category scores — performance, accessibility, best practices, SEO — and the lab metrics behind the performance score. device picks mobile (the default, throttled CPU and network) or desktop.

In Ruby the report is read with JSON.parse. Scores run from 0 to 1, so the program multiplies by 100 to print what the Lighthouse report shows; metrics carry a ready-formatted displayValue. The guide to reading a Lighthouse audit explains what each number means.

Setup

Before you start

Nothing to install: net/http and json are part of Ruby. Put your API key in the environment so it never lands in the file.

Terminal

ruby --version   # 3.1 or later
export URLPIPE_API_KEY="your_api_key"

The request

Print the four scores, LCP, CLS and TBT

sync: true keeps the request open until the result is ready. use_ssl: has to be asked for — Net::HTTP does not infer it from the scheme — and abort prints to stderr and exits 1. dig walks the nested keys and returns nil for a category or metric Lighthouse could not compute.

lighthouse_audit.rb

require "json"
require "net/http"

uri = URI("https://urlpipe.dev/lighthouse")
# read_timeout: a sync call can take up to 60 s, Net::HTTP's default.
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 90) do |http|
  http.post(uri.path, { url: "https://example.com", device: "mobile", sync: true }.to_json,
            "Authorization" => "Bearer #{ENV.fetch("URLPIPE_API_KEY")}",
            "Content-Type" => "application/json")
end
abort "URLpipe answered #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPOK)

report = JSON.parse(res.body)
%w[performance accessibility best-practices seo].each do |name|
  score = report.dig("categories", name, "score")
  puts "#{name}: #{score ? (score * 100).round : "n/a"}"
end

{
  "LCP" => "largest-contentful-paint",
  "CLS" => "cumulative-layout-shift",
  "TBT" => "total-blocking-time"
}.each do |label, key|
  puts "#{label}: #{report.dig("metrics", key, "displayValue") || "n/a"}"
end

Run it: ruby lighthouse_audit.rb

Given the example response on the docs page, it prints:

Output

performance: 95
accessibility: 88
best-practices: 92
seo: 90
LCP: 2.5 s
CLS: 0.05
TBT: 150 ms

Async

The async variant: a token, a webhook and a poll

Leave out sync and the answer is a token, straight away. Net::HTTP reports the status as a string, so the poll compares res.code with "202", not the number.

lighthouse_audit_async.rb

require "json"
require "net/http"

API = URI("https://urlpipe.dev")

def send_request(request)
  request["Authorization"] = "Bearer #{ENV.fetch("URLPIPE_API_KEY")}"
  Net::HTTP.start(API.host, API.port, use_ssl: API.scheme == "https") { |http| http.request(request) }
end

# No sync: the request is accepted at once and the work carries on without you.
post = Net::HTTP::Post.new(URI.join(API, "/lighthouse"), "Content-Type" => "application/json")
post.body = {
  url: "https://example.com",
  device: "mobile",
  report_to: "https://your-app.com/webhooks/urlpipe",
  labels: { customer: "acme" }
}.to_json
res = send_request(post)
abort "URLpipe answered #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPOK)
token = JSON.parse(res.body).fetch("token")
puts "Accepted #{token}"

# The result is POSTed to report_to when it is ready. Polling by token is the
# other way to collect it: no endpoint needed, and a backup for the webhook.
60.times do
  res = send_request(Net::HTTP::Get.new(URI.join(API, "/result/#{token}")))
  break unless res.code == "202" # 202 means still processing

  sleep 2
end

case res.code
when "200" then nil
when "202" then abort "Still processing after two minutes; try the token again later."
when "422" then abort "The analysis failed: #{JSON.parse(res.body)["error"]}"
when "410" then abort "The result is past the 30-day window; send the request again."
else abort "URLpipe answered #{res.code}: #{res.body}"
end

report = JSON.parse(res.body)
%w[performance accessibility best-practices seo].each do |name|
  score = report.dig("categories", name, "score")
  puts "#{name}: #{score ? (score * 100).round : "n/a"}"
end

{
  "LCP" => "largest-contentful-paint",
  "CLS" => "cumulative-layout-shift",
  "TBT" => "total-blocking-time"
}.each do |label, key|
  puts "#{label}: #{report.dig("metrics", key, "displayValue") || "n/a"}"
end

Run it: ruby lighthouse_audit_async.rb

Errors

Handle errors and retries

Pattern matching on [status, code] keeps the retry rules in one place. A 401 answers in plain text, so it is checked before JSON.parse, and a body that still is not JSON becomes an empty hash.

lighthouse_audit_errors.rb

require "json"
require "net/http"

class URLpipeError < StandardError; end

# POST a sync request and return the response, or raise URLpipeError.
def urlpipe(path, payload, attempts: 5)
  uri = URI("https://urlpipe.dev#{path}")
  attempts.times do |attempt|
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", read_timeout: 90) do |http|
      http.post(uri.path, payload.merge(sync: true).to_json,
                "Authorization" => "Bearer #{ENV.fetch("URLPIPE_API_KEY")}",
                "Content-Type" => "application/json")
    end
    return res if res.code == "200"
    raise URLpipeError, "401: the API key is missing or wrong. Check URLPIPE_API_KEY." if res.code == "401"

    body = begin
      JSON.parse(res.body)
    rescue JSON::ParserError
      {}
    end
    code = body["error"].to_s
    detail = body["message"] ? "#{code}: #{body["message"]}" : code

    case [ res.code, code ]
    in [ "429", "rate_limited" ]
      # Sending too fast: Retry-After says how long the window has left.
      sleep Integer(res["Retry-After"] || 1)
    in [ "429", "concurrency_limit" ]
      # Every parallel slot on your plan is busy with your own requests.
      sleep 2**attempt
    in [ "504", _ ]
      # Still running on our side; the token collects it from GET /result/:token.
      raise URLpipeError, "504 processing_timeout: collect it later with token #{body["token"]}"
    else
      # 403 email_unverified, 422 (a bad parameter, or a page that would not load),
      # 429 quota_exceeded: sending the same request again gets the same answer.
      raise URLpipeError, "#{res.code}: #{detail}"
    end
  end
  raise URLpipeError, "429: still refused after #{attempts} attempts"
end

begin
  res = urlpipe("/lighthouse", { url: "https://example.com", device: "mobile" })
rescue URLpipeError => e
  abort "URLpipe: #{e.message}"
end

report = JSON.parse(res.body)
%w[performance accessibility best-practices seo].each do |name|
  score = report.dig("categories", name, "score")
  puts "#{name}: #{score ? (score * 100).round : "n/a"}"
end

{
  "LCP" => "largest-contentful-paint",
  "CLS" => "cumulative-layout-shift",
  "TBT" => "total-blocking-time"
}.each do |label, key|
  puts "#{label}: #{report.dig("metrics", key, "displayValue") || "n/a"}"
end

Run it: ruby lighthouse_audit_errors.rb

Details

What to know about /lighthouse

Lighthouse 13 reports four categories; the pwa key is always null, kept so the shape does not change.
The performance score weights TBT 30%, LCP 25%, CLS 25%, FCP 10% and Speed Index 10%.
INP needs real users and cannot be measured in a lab run; TBT is its lab stand-in.
"include_audits": "true" adds the full list of audits, with the elements to fix. Mobile and desktop are cached separately.
Want the audit run on a schedule, with a history and alerts? Full Stack Audit sells that as a monitored report; URLpipe is the primitive underneath.

Endpoints

The endpoints on this page

Run a Lighthouse audit on any URL
Paste a link and get a real Google Lighthouse audit — performance, accessibility, best practices and SEO scores, plus Core Web Vitals — measured against the live page.
Try it free

/lighthouse API docs

Other languages

Run a Lighthouse audit in another language

Python Node.js PHP Go Java C#cURL

More Ruby: every Ruby recipe

FAQ

Frequently asked questions

Mobile or desktop — which device should I audit?

Mobile, unless you know your traffic is desktop. It emulates a 360×640 phone with a 4× slower CPU and a slow 4G network, which gives the lower, more telling scores. Pass device: "desktop" for a 1350×940 window with no throttling.

Why isn't INP in the results?

INP is measured from real users interacting with the page, which a lab audit cannot do. Total Blocking Time is the lab metric that tracks it.

Why use the async variant for Lighthouse?

An audit takes around 15 seconds, longer on a heavy page. Async hands you a token at once and delivers the report to your webhook, so nothing holds a connection open waiting.

Do I need an SDK to call URLpipe from Ruby?

No gem: Net::HTTP and json are in the standard library, and the API is one POST per job.

Keep reading

Run a Lighthouse audit in PHP Run a Lighthouse audit in Node.js Reading a Lighthouse audit Request timing as marks, not spans Total Blocking Time (TBT)Speed Index All of code recipes

Get a key and run it.

Free plan, no card. Paste your key into URLPIPE_API_KEY and every program on this page runs as it is.

Start free Email the team