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, use real public accounts, queries and URLs, and read the schema 2 response shape: posts, profiles, comments and transcripts look the same on every platform. Anything a recipe derives, such as an engagement rate or a sentiment score, it computes from those fields in your code.

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 most the call can cost with your parameters is held when it starts, and you are charged what it actually used. Failed calls, empty results and dry_run=1 calls are never charged. Repeating a call is charged again (2 credits when the shared cache answers it), so store what you fetch. 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, unavailable 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

A count the platform hides is null, never 0, so the recipes skip nulls rather than adding them. unavailable lists the fields a response could not fill on any row, for example ["items[].post.author.id"].

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