Node.js

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

RequirementsCopy Anchor Link

• Node.js 20+

InstallCopy Anchor Link

npm install @huntapi/sdk

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

import { HuntApiClient } from "@huntapi/sdk";

const client = new HuntApiClient({ apiKey: process.env.HUNTAPI_API_KEY });

const response = await client.mediaMetadata({
  query: "https://www.youtube.com/watch?v=Z5YP8kznWZs",
});
console.log(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.

const submitted = await client.videoDownload({
  query: "https://www.youtube.com/watch?v=Z5YP8kznWZs",
  video_quality: "720p",
});
const job = await client.waitForJob(submitted.data.job_id, {
  onProgress: (j) => console.log(`${j.status} ${j.progress ?? 0}%`),
});
console.log(JSON.stringify(job.data, null, 2));

ErrorsCopy Anchor Link

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

import { HuntApiApiError } from "@huntapi/sdk";

try {
  await client.mediaMetadata({
    query: "https://www.youtube.com/watch?v=Z5YP8kznWZs",
  });
} catch (error) {
  if (error instanceof HuntApiApiError) {
    console.error(error.status, error.message, error.responseBody);
  }
  throw error;
}

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.

const client = new HuntApiClient({ maxRetries: 5, retryDelay: 500 });

// or for one request
await client.mediaMetadata(
  { query: "https://www.youtube.com/watch?v=Z5YP8kznWZs" },
  { maxRetries: 0 },
);

Batch requestsCopy Anchor Link

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

const inputs = [
  "https://www.youtube.com/watch?v=Z5YP8kznWZs",
  "https://www.youtube.com/watch?v=jNQXAC9IVRw",
];
const results = await client.batch(
  inputs,
  (query) => client.mediaMetadata({ query }),
  { concurrency: 5 },
);

for (const result of results) {
  if (result.status === "fulfilled") console.log(result.value.data);
  else console.error(inputs[result.index], result.reason);
}

Any endpointCopy Anchor Link

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

const response = await 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/sdk
• Source code: github.com/huntapi/huntapi-node
• API reference