Credits and How Requests Are Billed

What a credit is

A credit is one request against one endpoint at its listed rate. Not one record, not one page of results, not one account. A followers drain that returns ten nonempty pages is ten billable requests. A profile call that returns a bio of two thousand characters is one. A successful first collection lookup that returns zero items is still charged at the endpoint rate: confirming that no results exist is a completed lookup. Exception: a successful cursor request returning zero items costs 0 on posts, reels-posts, reposts-posts, tagged-posts, comments, popular and hashtag. Their first requests still cost the endpoint rate even when empty. Private-account (200) and missing-target (200) lookups are billed at the same endpoint rate. Credits sit in a team balance shared by every key on the team, they do not expire, and there is no monthly reset.

Which endpoints cost 2

Followers and following. These lists are heavier to fetch and paginate deeply. Comments cost 1 credit per successful GET, except empty cursor pages, plus 0.5 for each reply page request when include_replies is enabled. Initial and additional reply pages are billed separately. The response reports reply_initial_requests, reply_cursor_requests, reply_total_requests and reply_total_credits for that GET; 5 reply page requests cost 2.5 reply credits, or 3.5 credits with the base fee. If comments are returned but no replies are returned, reply_total_credits is 0 and only the 1-credit base fee applies. If no comments are returned, the first request costs 1 credit and a request with a cursor costs 0; neither has a reply surcharge. Request counts remain visible even when reply fees are waived. Failed requests are not charged.

What is never charged

Exception: a successful cursor request returning zero items costs 0 on posts, reels-posts, reposts-posts, tagged-posts, comments, popular and hashtag. Their first requests still cost the endpoint rate even when empty. Invalid parameters (400), rejected keys (401), insufficient balance (402), upstream failures (500) and timeouts (504). Private-account (200) and missing-target (200) lookups are charged at the endpoint rate.

Reading the meter without a usage endpoint

credits_remaining is on every response, including errors, so your spend and your balance are already flowing through your normal request path. Summing credits_charged across a job gives you an exact cost for that job, and requested_at plus processing_time_ms gives you enough metadata to audit when each lookup ran.

let spent = 0;
let balance = null;

for (const handle of handles) {
  const res = await fetch(
    `https://api.socialscrape.dev/v1/instagram/profile?handle=${handle}`,
    { headers: { "x-api-key": process.env.INSCRAPE_KEY } },
  );
  const body = await res.json();

  spent += body.credits_charged;
  balance = body.credits_remaining;
  console.log(body.query.username, body.requested_at, body.processing_time_ms);
}

console.log(`spent ${spent}, balance ${balance}`);

Estimating a monthly budget

Count requests, not accounts. Take one unit of work, write down the endpoints it calls with their costs, then multiply by frequency. A creator card built from profile, twelve posts, reels and one page of followers is 1 + 1 + 1 + 2, so 5 credits. A roster of 500 creators refreshed weekly is 500 x 5 x 4.3, or roughly 10,750 credits a month. Do that arithmetic for each job you run and add them up; the total is what you should size a plan against.

// One creator card
const perCreator =
  1 + // profile
  1 + // posts (limit=12, one page)
  1 + // reels (one page)
  2;  // followers (one page, 2 credits)

const creators = 500;
const refreshesPerMonth = 4.3; // weekly

console.log(perCreator * creators * refreshesPerMonth); // 10750

Three ways a budget goes wrong

Budgeting per account instead of per request, which undercounts every paginated endpoint by however many pages you actually drain. Refreshing every number more often than your product needs. And draining a follower list to the end when a sample would answer the question: for audience quality checks, a few thousand sampled followers gives you the same distribution as a million at a small fraction of the cost.

Plans and prices

This page covers the mechanics only. Plan sizes, per-thousand prices and the buying decision live on the pricing page, along with the free allowance you start with.