herascrape
v0.1.8
Published
Official TypeScript/JavaScript client for the herascrape Instagram API.
Maintainers
Readme
herascrape: Instagram API client for TypeScript & JavaScript
herascrape is the official TypeScript/JavaScript client for
herascrape, a hosted Instagram scraper API. It reads
Instagram's public data for you and hands back Instagram's own JSON: profiles,
followers, posts, reels, comments, hashtags, locations, audio, stories and
search. You do not manage the accounts, devices or proxies.
import { Client } from "herascrape";
const client = new Client({ apiKey: "hs_live_xxxxxxxx" });
const user = await client.userByUsername({ username: "instagram" });
console.log(user.username, user.follower_count);
for await (const follower of client.iterUserFollowers({
userId: user.pk as string,
maxItems: 100,
})) {
console.log(follower.username);
}- 44 endpoints, one method each, plus lazy
iter*async iterators for lists. - Async-only, built on the native
fetchAPI. No runtime dependencies. - Ships ESM, CommonJS and TypeScript declarations. Node 18+.
- Typed exception hierarchy:
NotFoundError,PrivateAccountError,RateLimitErrorand the rest. - Retries with backoff,
Retry-Afterhandling and a client-side rate limiter.
Documentation: herascrape.com/docs.
Install
npm install herascrapeAuthentication
Create a key in the dashboard; the client
sends it in the x-api-key header. Pass it to the constructor:
import { Client } from "herascrape";
const client = new Client({ apiKey: "hs_live_xxxxxxxx" });Or leave it out and the client reads HERASCRAPE_API_KEY from the environment.
With no key in either place, constructing a client throws
AuthenticationError. Keep keys out of source control.
Billing is per successful call, and failed calls are not billed. See pricing.
Usage
Every method takes a single options object and returns the response data as a
plain object, exactly as Instagram sent it.
import { Client } from "herascrape";
const client = new Client({ apiKey: "hs_live_xxxxxxxx" });
// Profiles: look a username up once, then use the numeric pk.
const user = await client.userByUsername({ username: "instagram" });
const page = await client.userFollowers({ userId: user.pk as string });
console.log(page.items, page.has_more, page.next_cursor);
// Pagination: iter* walks the pages lazily.
for await (const reel of client.iterUserReels({
userId: user.pk as string,
maxItems: 50,
})) {
console.log(reel.code);
}
// Search: session UUIDs are generated for you.
const hits = await client.searchUsers({ query: "nike" });
for (const hit of hits.items as Array<Record<string, unknown>>) {
console.log(hit.pk, hit.username);
}
// Posts take a pk or a shortcode.
const post = await client.post({ postId: "B4XpqViUFUI" });
console.log(post.like_count, post.comment_count);
// Convert between a media pk and its shortcode.
console.log(await client.resolveMedia({ code: "B4XpqViUFUI" }));Most list responses carry items, next_cursor and has_more. postComments
and userPosts keep Instagram's own paging shape, so they have no iterator and
you page them by hand, and searchTop returns edges with next_cursor only;
see
the docs.
Errors
Every exception inherits from HerascrapeError. API errors are
HerascrapeApiError subclasses carrying statusCode, errorCode, detail
and requestId.
import { Client, PrivateAccountError, ProfileNotFoundError } from "herascrape";
const client = new Client({ apiKey: "hs_live_xxxxxxxx" });
try {
await client.userFollowers({ userId: "25025320" });
} catch (error) {
if (error instanceof PrivateAccountError) console.log("private account");
else if (error instanceof ProfileNotFoundError) console.log("no such profile");
else throw error;
}| Exception | When |
| --- | --- |
| BadRequestError | 400. InvalidCursorError and InvalidParameterError are subclasses. |
| AuthenticationError | 401. Missing or invalid key. |
| ForbiddenError | 403. PrivateAccountError is the private-profile case. |
| NotFoundError | 404. ProfileNotFoundError is the unknown-profile case. |
| ValidationError | 422. Per-field messages in fieldErrors. |
| RateLimitError | 429. Seconds to wait in retryAfter, when sent. |
| ServerError | 5xx. InternalError, UpstreamError and ServiceUnavailableError are subclasses. |
| HerascrapeTransportError | No response: connection failure or timeout. |
Retries and rate limiting
The client retries connection errors and timeouts, 429, 502, 503 and
invalid_cursor up to maxRetries times (default 3), backing off from 0.5 s
to 8 s with jitter. A 429 with a Retry-After header waits that long, capped
at 300 s. It also throttles requests on the client with a token bucket that
defaults to 50 requests per second. Match it to your account's limit, which
all of its API keys share:
import { Client } from "herascrape";
const client = new Client({ rateLimit: { rate: 10, period: "s" } });
const unthrottled = new Client({ rateLimit: null }); // no client-side limitOther constructor options: timeout (seconds, default 10), maxRetries, and
baseUrl (default https://api.herascrape.com).
Endpoints
All 44 endpoints are GETs, grouped below. Paginable list endpoints also get a
matching iter* async iterator.
| Group | Methods |
| --- | --- |
| Users | userByUsername, user, userFollowers, userFollowing, userPosts, userReels, userTagged, userStories, userHighlights, userReposts, userAbout, userSimilar |
| Posts and comments | post, postComments, postLikers, postLikersAll, postCounts, commentReplies, commentLikers |
| Search | searchUsers, searchHashtags, searchAudio, searchTop, searchPlaces, searchReels |
| Hashtags | hashtag, hashtagTop, hashtagRecent, hashtagReels |
| Locations | location, locationTop, locationRecent |
| Audio | audioTrending, audio, audioMedias |
| Stories and highlights | highlight, story, storyTemplate, storyTemplateParticipants, storyTemplateStories |
| Utility | resolveMedia, oembed, balance, health |
Coming from HikerAPI? The migration guide maps each path to its herascrape equivalent.
Disclaimer
herascrape is not affiliated with, authorized, maintained, or endorsed by Instagram or Meta. Instagram is a trademark of Meta Platforms, Inc. You are responsible for using the data in line with applicable law and Instagram's terms.
