Ruby

The official Ruby SDK for HuntAPI, with one typed method per endpoint and a generic request() for anything else.

RequirementsCopy Anchor Link

• Ruby 3.1+

InstallCopy Anchor Link

gem install huntapi

gem "huntapi"

Get your API keyCopy Anchor Link

Copy your API key from the HuntAPI dashboard and set it in the HUNTAPI_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.

Quick startCopy Anchor Link

require "huntapi"

client = HuntApi::Client.new(api_key: ENV.fetch("HUNTAPI_API_KEY"))
response = client.media_metadata(query: "https://www.youtube.com/watch?v=Z5YP8kznWZs")
puts response.data

Async jobsCopy Anchor Link

Download endpoints are asynchronous: they return a job_id, and jobs can run for up to 12 hours. The SDK can wait for the job to finish.

submitted = client.video_download(query: "https://www.youtube.com/watch?v=Z5YP8kznWZs", video_quality: "720p")
job = client.wait_for_job(submitted.data["job_id"]) { |j| puts "#{j['status']} #{j['progress']}%" }
puts job.data

ErrorsCopy Anchor Link

A non-2xx response raises an API error with its status and message. See Status codes for the full list.

begin
  client.media_metadata(query: "https://www.youtube.com/watch?v=Z5YP8kznWZs")
rescue HuntApi::APIError => e
  warn "HTTP #{e.status}: #{e.message}"
end

RetriesCopy Anchor Link

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.

client = HuntApi::Client.new(max_retries: 5, retry_delay: 0.5)
client.media_metadata(query: "https://www.youtube.com/watch?v=Z5YP8kznWZs", request_options: { max_retries: 0 }) # one request without retries

Batch requestsCopy Anchor Link

Run many calls at once, 10 at a time by default. One failure does not stop the others.

inputs = ["https://www.youtube.com/watch?v=Z5YP8kznWZs", "https://www.youtube.com/watch?v=jNQXAC9IVRw"]
results = client.batch(inputs, concurrency: 5) { |value| client.media_metadata(query: value) }
results.each do |result|
  if result.ok?
    puts result.value.data
  else
    warn "#{inputs[result.index]}: #{result.error.message}"
  end
end

Any endpointCopy Anchor Link

request() reaches any path, including endpoints released after your SDK version.

response = client.request("GET", "/v1/usage")

Common mistakesCopy Anchor Link

• Putting the API key in front-end code. Anyone could read it. Call the API from your server.
• Treating every 401 as a bad key. A 401 can also be a rate limit: read the message. The SDK retries plan rate limits for you.
• Retrying a 402. It means there are no credits or quota left, so a retry cannot succeed. See Credits.
• Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.

LinksCopy Anchor Link

• Package: huntapi
• Source code: github.com/huntapi/huntapi-ruby
• API reference