Credits

Every call is priced per endpoint in credits. A fixed endpoint always costs the same; a metered endpoint quotes a range and charges what the call actually used. Calls that fail or find nothing cost nothing. Your balance is the same one you use for InsightSocial exports.

What does a call cost?

Each endpoint has its own price, listed on its reference page and in the full table at Endpoint pricing. There are two kinds.

Fixed. One number, charged on every successful call.

Metered. A range. What you pay depends on how much the call reads, for example how many pages of comments it walked.

GET /v1/endpoints returns the same prices as JSON: credits is a number for a fixed endpoint and { "min", "max" } for a metered one. It needs no key and costs nothing.

Reserve the ceiling, settle the actual

Before a call runs, we hold its ceiling against your balance: the fixed price, or the top of a metered range. When the call finishes, we charge what it really used and release the rest. On a metered endpoint credits_used is often well below the ceiling.

You never pay more than the ceiling. If you send max_pages (see Pagination), the ceiling is the listed maximum multiplied by max_pages, and that product is the most the call can cost.

If your balance cannot cover the ceiling, the call is refused before it starts:

{
  "success": false,
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "message": "This call needs up to 340 credits and 120 remain. Top up at https://www.insightsocial.app/pricing"
  },
  "request_id": "req_1a2b3c4d5e6f",
  "credits_used": 0,
  "credits_remaining": 120
}

The status is 402 and nothing is charged.

Why a call cost what it did

Every successful response carries charge_reason, so you can tell why credits_used has the value it has.

Errors are never charged either: every error response has credits_used: 0.

Re-running a call you already paid for

Inside a window after a paid call, the exact same call from your account is free (charge_reason: "owned"). "Exact" means the same path and the same query parameters; their order does not matter, and any key on your account counts. The window depends on the kind of endpoint:

Each endpoint's page states its own window ("Re-running the exact same call within 24h is free"), and /v1/endpoints publishes it as cache_ttl_seconds. The window starts at the last paid call; free re-runs do not extend it. A call that forces a fresh fetch is never owned. See Caching.

Price a call without running it

On endpoints that accept dry_run=1, the response reports an estimate in data.estimate and costs 0 credits. The parameter is listed on each endpoint that supports it.

Free calls

Every account gets 10 free calls, once, for its lifetime. A free call is any call that would have been charged (a miss or a shared_cache) whose ceiling is 200 credits or less. It comes back with free_call: true and credits_used: 0, and it counts as paid for the owned window.

Calls above 200 credits are charged normally even while free calls remain. Owned re-runs, empty results, errors and replays of a call we already answered never use one up. The one replay that can use a free call is a replay of a call we never answered successfully, because that replay is charged; see Production checklist.

Where your credits come from

The monthly grant is spent first and pack credits second. Referral bonuses are added to your pack credits.

This is one balance, shared with InsightSocial exports. Credits you spend on the API reduce what you can export, and the other way round.

Buy a plan or a pack at insightsocial.app/pricing.

How do I check my balance?

1. On every response. The body has credits_remaining, and the X-Credits-Remaining header carries the same number. The header is left out when the balance could not be read.
2. With GET /v1/credits. Needs your key, costs 0 credits.
3. In the dashboard. The API section of your portal shows balance, usage and an activity log.

curl "https://api.insightsocial.app/v1/credits" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

{
  "success": true,
  "credits_used": 0,
  "credits_remaining": 9180,
  "plan": { "tier": "pro", "credits_per_month": 10000, "resets_at": "2026-10-01T00:00:00.000Z" },
  "usage": { "window_start": "2026-09-01T00:00:00.000Z", "used": 1320, "used_export": 400, "used_api": 920 },
  "pack_credits": 500,
  "free_calls": { "remaining": 0, "total": 10 },
  "key": { "id": "3f6c2a8e-7b41-4d0f-9a52-1c8e5d7b9f20", "name": "production" },
  "request_id": "req_1a2b3c4d5e6f"
}

Retries with an Idempotency-Key are not charged twice

Send an Idempotency-Key header and retry with the same value. A replay of a call we already answered comes back with idempotent_replay: true, charge_reason: "replay" and credits_used: 0. See Production checklist for the key format and the edge cases.

Next steps