Recipes

Each recipe solves one real task from start to finish and tells you what a run costs before you start. The snippets are Python (3.9+, requests), with Node.js (22+, native fetch) where a recipe benefits from both. They read your key from INSIGHTSOCIAL_API_KEY and use real public accounts, queries and URLs.

New to the API? The Quickstart gets you a key and a first call in a few minutes.

Pick a recipe

Where a price is a range, at least one endpoint in the recipe is metered: the top of its range is held when the call starts and you are charged what it actually used. Failed calls, empty results and dry_run=1 calls are never charged, and repeating the exact same call inside its window (1 hour for search, 6 hours for most lists, 24 hours for profiles) costs 0. API credits are non-refundable. See Credits.

Which recipe should I start with?

If you want to see the breadth of the API, start with Brand mention monitoring. It runs six platforms' search endpoints in parallel from one key, with one response envelope to handle.

If you already know the platform, the TikTok analytics dashboard is the shortest complete example: three calls, one account.

The helper every recipe uses

Every recipe calls the API through the same small function. It sends the key in x-api-key, raises on a failed call, and returns the whole envelope so you can read data, pagination and credits_used.

import os
import requests

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

def get(path, **params):
    res = requests.get(
        f"{BASE}/{path}",
        params=params,
        headers={"x-api-key": KEY},
        timeout=120,
    )
    body = res.json()
    if not body["success"]:
        raise RuntimeError(f'{body["error"]["type"]}: {body["error"]["message"]}')
    return body

Two limits shape how the recipes run calls in parallel: 60 requests per minute and 10 calls in flight per key. The recipes keep their thread pools at 10 or fewer. See Rate limits.

Related