Introduction

InsightSocial API gives you public data from 25 social platforms through more than 300 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 10 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, 25 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 the answer has one shape everywhere: a profile is a profile, a post is a post, whichever platform it came from. A field a platform does not show is null. See Schema 2.

The response envelope

Every successful call to a data endpoint returns a body with this top level, and the platform payload sits under data. A failed call returns a smaller error body instead: success: false, an error object with type, message and sometimes param, plus request_id, credits_used and credits_remaining, and no schema_version, data or unavailable; see Errors. GET /v1/credits and GET /v1/endpoints return bodies of their own; see Response schema.

{
  "success": true,
  "platform": "instagram",
  "endpoint": "/v1/instagram/profile",
  "schema_version": "2",
  "data": {
    "author": {
      "id": "528817151",
      "username": "nasa",
      "display_name": "NASA",
      "followers": 104294818,
      "url": "https://www.instagram.com/nasa/",
      "external_url": "https://www.nasa.gov"
    }
  },
  "unavailable": [],
  "credits_used": 10,
  "credits_remaining": 490,
  "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 100 credits or less are free.
• Failed calls, empty results and dry_run calls are never charged.
• Repeating a call is charged again. Only an Idempotency-Key replay is free.
• 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