Ruby · Code recipe
Get a page's metadata and Open Graph tags in Ruby
Read the title, description and share image of any page, 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 read a page's title, description, Open Graph image and other metadata in Ruby, POST its URL to https://urlpipe.dev/meta with sync set to true and parse the JSON with JSON.parse. It answers with nine fields, any of which can be null, for 5 credits: it is one of the three endpoints that call a language model.
Free plan, no credit card. 1,000 credits a month.
One POST to /meta renders the page and returns what it says about itself: title, description, language, main image, favicon, author, feed, first publication date and extra author details. URLs come back absolute, resolved against the page.
A language model reads the page's metadata declarations — Open Graph, Twitter cards, JSON-LD, plain tags — and settles conflicts by a fixed order: og:title, then twitter:title, then <title>, then the <h1>. A field the page never declares is null, never a guess. That is why it costs 5 credits where a page fetch costs 1 credit. In Ruby, JSON.parse gives you the fields; the Open Graph guide covers which tags each platform reads.
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.
ruby --version # 3.1 or later
export URLPIPE_API_KEY="your_api_key"
The request
Print the title, description and main image
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. Any field can be nil, hence the || "none".
require "json"
require "net/http"
uri = URI("https://urlpipe.dev/meta")
# 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", 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)
meta = JSON.parse(res.body)
puts "Title: #{meta["title"] || "none"}"
puts "Description: #{meta["description"] || "none"}"
puts "Image: #{meta["main_image_url"] || "none"}"
Run it: ruby page_metadata.rb
Given the example response on the docs page, it prints:
Title: Example Domain
Description: Illustrative examples in documents.
Image: https://example.com/cover.jpgAsync
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.
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, "/meta"), "Content-Type" => "application/json")
post.body = {
url: "https://example.com",
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
meta = JSON.parse(res.body)
puts "Title: #{meta["title"] || "none"}"
puts "Description: #{meta["description"] || "none"}"
puts "Image: #{meta["main_image_url"] || "none"}"
Run it: ruby page_metadata_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.
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("/meta", { url: "https://example.com" })
rescue URLpipeError => e
abort "URLpipe: #{e.message}"
end
meta = JSON.parse(res.body)
puts "Title: #{meta["title"] || "none"}"
puts "Description: #{meta["description"] || "none"}"
puts "Image: #{meta["main_image_url"] || "none"}"
Run it: ruby page_metadata_errors.rb
Details
What to know about /meta
- Any field can be
nullwhen the page does not have it — code for that, as the program does. - There is no
canonicalfield; the nine fields are the whole response. - Image and favicon URLs that are data URIs come back as
nullrather than as a blob. - Pages over 10 MB of HTML are refused before the model sees them.
FAQ
Frequently asked questions
Which fields does /meta return?
Why does metadata cost more than fetching the HTML?
Is AI processing done in the EU?
Do I need an SDK to call URLpipe from Ruby?
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.