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 is needed: Net::HTTP and json are in the standard library, and the API is one POST per job. If you'd rather use one, the official client installs with gem install urlpipe and adds retries that never bill twice, typed errors and webhook verification.

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

Client library

Or use the official Ruby client

The same call in one line, with retries that never bill twice, typed errors, long analyses waited out for you and webhook verification. Ruby 3.1+, no dependencies.

urlpipe

# gem install urlpipe

require "urlpipe"

client = Urlpipe::Client.new # reads ENV["URLPIPE_API_KEY"]

page = client.markdown("https://example.com")
puts page.data

Client libraries in the docs Ruby client on GitHub

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, 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.

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