Introduction

InsightSocial API gives you public data from nine social platforms through 238 GET endpoints. You authenticate every call with the same x-api-key header, every answer arrives in the same JSON envelope, and every call draws on one credit balance, the same one you already use for InsightSocial exports.

Your first call

curl "https://api.insightsocial.app/v1/tiktok/profile?handle=khaby.lame" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

That is the whole protocol: one GET request with one header. The profile call costs 20 credits, and the response tells you what you were charged and what is left, so you never need a separate balance check to keep track.

One request shape, nine platforms

Switch platforms by changing one path segment. The header stays the same and the envelope stays the same.

curl "https://api.insightsocial.app/v1/tiktok/profile?handle=nasa" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

curl "https://api.insightsocial.app/v1/instagram/profile?handle=nasa" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

curl "https://api.insightsocial.app/v1/youtube/channel?handle=nasa" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

curl "https://api.insightsocial.app/v1/twitter/profile?handle=nasa" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

The platforms differ in what they expose, so field coverage differs too, but you parse all four answers the same way.

The response envelope

Every data endpoint, whether the call succeeds or fails, returns a body with this top level, and the platform payload sits under data. GET /v1/credits and GET /v1/endpoints return bodies of their own; see Response schema.

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "author": { "username": "nasa", "followers": 3900000 }
  },
  "credits_used": 20,
  "credits_remaining": 480,
  "request_id": "req_1a2b3c4d5e6f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": false
}

List endpoints add a top-level pagination object. Send pagination.next_cursor back unchanged as cursor until has_more is false. See Pagination and Response schema.

Browse the catalogue for free

GET /v1/endpoints lists every endpoint with its price, parameters and whether it paginates. It needs no key and costs nothing. GET /v1/credits returns your balance, also free.

# Every Instagram endpoint, with prices and parameters
curl "https://api.insightsocial.app/v1/endpoints?platform=instagram"

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

What calls cost

Each endpoint has its own price in credits, listed in Endpoint pricing and on every API reference page. Some endpoints are metered: you see a range, we hold the top of the range while the call runs, and you pay what the call actually used.

• The free plan includes 500 credits a month and Pro includes 10,000. Credit packs are on the pricing page.
• Your first 10 calls priced at 200 credits or less are free.
• Failed calls, empty results and dry_run calls are never charged.
• Repeating the exact same call within its ownership window costs nothing.
• API credits are non-refundable.

See Credits for the full rules. Every key is limited to 60 requests a minute and 10 in flight; see Rate limits.

When a call fails

Failures use the same envelope with success: false. Branch on error.type, not on the message text.

The complete list, with retry advice, is in Errors.

Next steps