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_. You can show or copy the full value from the dashboard at any time. Keep it in a secret store rather than in your code, and 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/instagram/profile?handle=nasa" \
  -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": "instagram",
  "endpoint": "/v1/instagram/profile",
  "schema_version": "2",
  "data": {
    "author": {
      "id": "528817151",
      "username": "nasa",
      "display_name": "NASA",
      "avatar_url": "https://scontent-phl2-1.cdninstagram.com/…",
      "bio": "Making the seemingly impossible, possible. ✨",
      "verified": true,
      "followers": 104294818,
      "followers_approximate": null,
      "following": 90,
      "posts_count": 4942,
      "likes_count": null,
      "url": "https://www.instagram.com/nasa/",
      "location": null,
      "external_url": "https://www.nasa.gov",
      "private": false,
      "joined_at": null,
      "last_post_at": "2026-10-03T14:10:18.000Z",
      "ext": { "business_category": null }
    }
  },
  "unavailable": [],
  "credits_used": 0,
  "credits_remaining": 500,
  "request_id": "req_d6ad52ab1f9f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": true
}

The payload is under data. A profile has the same fields on every platform; a field the platform does not show is null (Instagram shows no likes_count or joined_at). Ids are always strings and times are ISO 8601 in UTC. schema_version says which response shape you got, and unavailable lists any field this platform normally fills that this response could not; it is empty here. See Schema 2. 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 100 credits or less cost nothing, so this 10-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 40 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 10 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 v2c. and are opaque: do not parse or edit them. Send them back only as cursor, with the same other parameters as the first page, within 24 hours. Details in Pagination.