Using an AI agent

You do not have to read the rest of these docs before you start. Paste the prompt below into your agent and it will read the free endpoint catalogue, check your key and make the first calls for you. Everything happens over plain HTTPS: one base URL, one header, one JSON envelope, so there is nothing you have to install.

If your agent supports MCP or Agent Skills, one command sets up both instead: npx -y insightsocial init. See MCP server, CLI and agent skills. For workflows in n8n, see n8n.

Why the catalogue matters

GET https://api.insightsocial.app/v1/endpoints is public and free, and it needs no key. It lists every endpoint with its description, every parameter (name, type, whether it is required, allowed values, an example) and its price in credits. An agent that reads it before planning a call never invents a path or a parameter, and it can tell you what a job will cost before it spends anything.

# Every endpoint on one platform
curl "https://api.insightsocial.app/v1/endpoints?platform=tiktok"

{
  "path": "/v1/tiktok/profile",
  "method": "GET",
  "platform": "tiktok",
  "description": "Returns a TikTok account's public profile: display name, bio, follower count ...",
  "credits": 20,
  "paginates": false,
  "cache_ttl_seconds": 86400,
  "params": [
    { "name": "handle", "required": false, "in": "query", "type": "string",
      "example": "charlidamelio", "one_of_group": "handle|user_id" },
    { "name": "user_id", "required": false, "in": "query", "type": "string",
      "one_of_group": "handle|user_id" }
  ],
  "available": true
}

A few fields worth knowing:

?platform= takes one platform id, such as instagram, tiktok, bluesky or weibo (the full list is under UNKNOWN_PLATFORM). Leave it off to get all 25 platforms at once.

If your tooling generates clients or agent tools from OpenAPI, the same surface is published as an OpenAPI 3.1 spec at GET https://api.insightsocial.app/v1/openapi.json, also free and keyless.

Give it the docs as Markdown

The quickest start is one link: https://www.insightsocial.app/docs/api-reference.md lists every endpoint with its path, a one-line description and its required parameters, and links to each endpoint's full page. Give it to your assistant together with your key and say what data you want.

Every page of these docs is also plain Markdown: add .md to its URL, for example https://www.insightsocial.app/docs/pagination.md. Two more files cover the whole site:

• https://www.insightsocial.app/docs/llms.txt lists every page, one line each.
• https://www.insightsocial.app/docs/llms-full.txt is every page in one file.

Paste either into a chat, or let an agent that can fetch URLs read them itself.

Copy the prompt

Put your key in the environment first, so it never appears in the chat:

export INSIGHTSOCIAL_API_KEY=isk_live_...

Then paste this into your agent:

Set up the InsightSocial API in this project and make a first successful call.

Facts you can rely on:
- Base URL: https://api.insightsocial.app/v1
- Auth: send the header `x-api-key: $INSIGHTSOCIAL_API_KEY` on every request. Read the key from
  the environment. Never print it, put it in a URL, or commit it. Authorization: Bearer is refused.
- All data endpoints are GET with query parameters.
- Success responses look like: { success: true, platform, endpoint, schema_version: "2", data,
  pagination?, unavailable, credits_used, credits_remaining, request_id, cached,
  idempotent_replay, charge_reason, free_call }. List responses put rows in data.items
  (each { post }, { author } or { comment }) and add pagination { next_cursor, has_more }.
  unavailable lists fields (paths into data) this response could not fill.
- Ids are strings, times are ISO 8601 UTC. null means unknown, never zero.
- Responses carry data only: no engagement rate, labels or relevance scores. Compute what you
  need from the raw counts. Parameters that ask for analysis (label, relevance, relevant_to,
  judgments, fit, brand, ...) are refused with 400 UNSUPPORTED_PARAMETER and error.param.
- Error responses look like: { success: false, error: { type, message, param? }, request_id,
  credits_used, credits_remaining }.
- Prices are per endpoint, in credits. Failed calls, empty results and dry_run=1 calls are
  never charged. Repeating a call is charged again, so store responses you need twice.

Before writing any call, read the reference instead of guessing paths or parameters:
  https://www.insightsocial.app/docs/api-reference.md
For prices and allowed values, read the catalogue. It is free and needs no key:
  GET https://api.insightsocial.app/v1/endpoints
  GET https://api.insightsocial.app/v1/endpoints?platform=<platform>
Use only endpoints where available is true, only parameters listed for that endpoint,
and tell me the price (credits, or min-max for metered) before any call over 50 credits.

Then, in order:
1. Verify the key with GET https://api.insightsocial.app/v1/credits (free) and print
   credits_remaining.
2. Call GET https://api.insightsocial.app/v1/tiktok/profile?handle=khaby.lame and print
   data.author.followers and credits_used.
3. Read the same kind of account on instagram/profile (handle=natgeo), youtube/channel
   (handle=mkbhd) and twitter/profile (handle=nasa). Print one line per platform.
4. Pick one list endpoint from the catalogue whose paginates is true, and read two pages by
   sending pagination.next_cursor back as ?cursor= while has_more is true. Send cursor values
   back unchanged, with the same other parameters as page 1.

Rules:
- Check `success` before using `data`. Branch on error.type, never on the message text.
- Retry only on HTTP 429, HTTP 503, IDEMPOTENCY_IN_PROGRESS and INTERNAL_ERROR.
  On a 400, read error.param and fix or remove that parameter before trying again. Wait for the
  Retry-After header when present, then back off with jitter. Never retry other 4xx errors.
- On INSUFFICIENT_CREDITS, stop and tell me. Do not retry.
- Stay under 60 requests per minute and 10 requests in flight.
- Stop and ask me before spending more than 500 credits in total.

The prompt pins down the three things an agent must not guess (the base URL, the header and the response shape), sends it to the catalogue before it writes a call, and gives it four concrete tasks that end with accounts read on four platforms. The whole exercise costs roughly 60 to 100 credits, and on a new account the 10 free calls cover most of it.

What the agent will do first

A good agent run starts the same way every time, and you can ask for these steps by name:

curl "https://api.insightsocial.app/v1/credits" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY"

Wiring the API into your own agent

When you build the agent yourself, one generic HTTP tool is enough: the model picks the path and parameters from the catalogue, and your tool makes the call. Keep the key in your code, not in the model's context.

import os
import requests

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

# Give the model this catalogue once, as reference text or a second tool.
CATALOGUE = requests.get(f"{BASE}/endpoints", timeout=30).json()

def insightsocial_get(path: str, params: dict) -> dict:
    """Tool: call one InsightSocial endpoint, e.g. path='tiktok/profile'."""
    res = requests.get(f"{BASE}/{path.removeprefix('/v1/').lstrip('/')}",
                       params=params, headers={"x-api-key": KEY}, timeout=120)
    body = res.json()
    if not body["success"]:
        # Hand the model a short instruction, not a raw error envelope.
        retry = res.headers.get("Retry-After")
        return {"error": body["error"]["type"], "message": body["error"]["message"],
                "retry_after_seconds": retry}
    return {"data": body["data"], "pagination": body.get("pagination"),
            "credits_used": body["credits_used"],
            "credits_remaining": body["credits_remaining"]}

Describe the tool to the model with two parameters, path (string, for example tiktok/profile) and params (object of query parameters). This works with Claude tool use, OpenAI function calling or any agent framework, because it is only an HTTP request.

Three habits keep an agent loop cheap and correct:

• Return a short error, not the envelope. A model given a raw success: false body tends to reason around it. Hand it the error.type and let your code decide whether to retry.
• Watch the budget. Every response carries credits_used and credits_remaining. Stop the loop on a budget you set, and cap the number of tool steps.
• Price before you call. For metered endpoints the catalogue's max is what the call holds up front. dry_run=1 returns our quote in data.dry_run (credits_min, credits_max) with charge_reason: "dry_run", and is never charged.

Troubleshooting

The agent gets MISSING_API_KEY. It is almost certainly putting the key in Authorization: Bearer. That header is ignored: the API looks for the key in x-api-key and nowhere else, so a Bearer-only request arrives with no key at all. INVALID_API_KEY is different: the x-api-key header is present but its value is wrong, such as a token that does not start with isk_ or a key that does not exist.

It invents parameters. Unknown parameters are passed along and may be rejected with a 400. Errors are never charged, but they waste a round trip. Tell the agent to read GET /v1/endpoints?platform=<platform> first and use only the listed params.

It gets UNSUPPORTED_PARAMETER. The agent sent a parameter that asks for analysis, such as relevance, relevant_to or label, often copied from older examples. error.param names it. Have the agent drop it and filter or score the rows itself; see Schema 2.

It gets CURSOR_INVALID on page 2. It changed a parameter between pages, sent the cursor under another name, or reused a cursor from the previous schema. A cursor works only as cursor, with the first page's parameters, for 24 hours. See Pagination.

It hits RATE_LIMITED or CONCURRENCY_LIMIT. Each key allows 60 requests per minute and 10 in flight. Have the agent honour Retry-After and run fewer calls in parallel. See Rate limits.

It gets INSUFFICIENT_CREDITS on a call that should be cheap. A metered call holds its ceiling before it runs, so the balance has to cover max, not the final charge. Top up at insightsocial.app/pricing. API credits share one balance with your InsightSocial export credits, and they are non-refundable. Calls that fail or return nothing are simply never charged.

It keeps paying for the same data. Every repeat of a call is charged. Have the agent keep the responses it already has instead of calling again, and make sure it is not adding fresh=1 or Cache-Control: no-cache, which skip the 2-credit shared cache and force a full-price fetch.

Next steps