Quickstart

Get your API key

Sign in and open API keys in the dashboard. Your first key is created for you the first time you visit the API section; you can make more there at any time.

A key starts with isk_live_. The full value is shown only once, so copy it into a secret store straight away, then export it for the examples below:

export INSIGHTSOCIAL_API_KEY="isk_live_..."

Keep the key on your server. See Authentication for rotation and revocation.

Make your first call

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

No token exchange and no per-platform setup: the header is the whole credential.

Read the response

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": {
    "author": {
      "username": "khaby.lame",
      "followers": 162000000,
      "following": 80
    }
  },
  "credits_used": 0,
  "credits_remaining": 500,
  "request_id": "req_1a2b3c4d5e6f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": true
}

The payload is under data. credits_used is what this call cost and credits_remaining is your balance after it. Here free_call is true: your first 10 calls priced at 200 credits or less cost nothing, so this 20-credit call came out of that allowance.

The same numbers are also sent as headers, which is handy for logging:

Every field is described in Response schema.

Read four platforms in one script

Changing platform means changing the path, nothing else. This loop reads the same handle on four platforms, prints the follower count and the running cost, and spends up to 80 credits (less while you still have free calls).

import os
import requests

KEY = os.environ["INSIGHTSOCIAL_API_KEY"]
BASE = "https://api.insightsocial.app/v1"

for path in ["tiktok/profile", "instagram/profile", "youtube/channel", "twitter/profile"]:
    body = requests.get(
        f"{BASE}/{path}",
        params={"handle": "nasa"},
        headers={"x-api-key": KEY},
    ).json()
    if not body["success"]:
        print(path, body["error"]["type"], body["error"]["message"])
        continue
    followers = body["data"]["author"]["followers"]
    print(f"{path:<20} {followers:>14,}  cost {body['credits_used']}  left {body['credits_remaining']}")

Page through a list

List endpoints return a pagination object next to data. Send pagination.next_cursor back as the cursor parameter, exactly as you received it, and stop when has_more is false. This walks the first three pages of NASA's followers on X, at 20 credits a page.

import os
import requests

KEY = os.environ["INSIGHTSOCIAL_API_KEY"]
URL = "https://api.insightsocial.app/v1/twitter/user/followers"

params = {"handle": "nasa"}
for page in range(3):
    body = requests.get(URL, params=params, headers={"x-api-key": KEY}).json()
    if not body["success"]:
        print(body["error"]["type"], body["error"]["message"])
        break
    print("page", page + 1, "rows", len(body["data"].get("items", [])))
    pagination = body.get("pagination") or {}
    if not pagination.get("has_more"):
        break
    params["cursor"] = pagination["next_cursor"]

Cursors start with is2. and are opaque: do not parse or edit them. A few endpoints page with their own parameter, such as page or continuationToken; each endpoint's reference page names it. Details in Pagination.