Response schema

Every data endpoint answers in one envelope, success or error, so a single parser handles all nine platforms. The two account endpoints are the exception: GET /v1/credits returns a balance body of its own (it still carries success, credits_used and credits_remaining), and GET /v1/endpoints returns the catalogue in its own shape.

Successful response

{
  "success": true,
  "platform": "instagram",
  "endpoint": "/v1/instagram/profile",
  "data": {
    "author": { "username": "natgeo", "followers": 276000000 }
  },
  "credits_used": 20,
  "credits_remaining": 9980,
  "request_id": "req_1a2b3c4d5e6f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": false
}

Envelope fields

charge_reason

Ownership windows and the other pricing rules are on Credits.

Fields inside data

Two fields live inside data rather than at the root of the envelope.

data.dropped. On list endpoints, counts items left out of the page because they could not be mapped to the endpoint's schema. A healthy page carries "dropped": 0. It is the only sign that a page came back short, so check it on every page instead of judging completeness by the length of items.

data._warnings. An array of human-readable notes, present only when something about the data was ambiguous or partial:

{
  "data": {
    "author": { "username": "natgeo" },
    "_warnings": [
      "posts: one call reads one page of 12 posts; pass posts_cursor back as cursor for the next page"
    ]
  }
}

Treat warnings as advisory. The response is still valid. When there is nothing to report, the key is absent.

Endpoints that attach computed fields or labels return them inside data as well.

Error response

{
  "success": false,
  "error": {
    "type": "INSUFFICIENT_CREDITS",
    "message": "This call needs up to 340 credits and 120 remain. Top up at https://www.insightsocial.app/pricing"
  },
  "request_id": "req_1a2b3c4d5e6f",
  "credits_used": 0,
  "credits_remaining": 120
}

The full list of types is on Errors.

Response headers

CORS headers are also set, and X-Request-Id, X-Credits-Used, X-Credits-Remaining and Retry-After are exposed to browser code. Keys still belong on your server; see Authentication.

List endpoints

List responses put their rows in data.items and carry a pagination object at the root of the envelope:

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/search",
  "data": {
    "items": [
      /* ... */
    ],
    "dropped": 0
  },
  "pagination": {
    "next_cursor": "is2.eyJ2IjoyLCJwIjoiNDgyMTk5NjAzNzEifQ",
    "has_more": true,
    "page_size": 30
  },
  "credits_used": 20,
  "credits_remaining": 9960,
  "request_id": "req_1a2b3c4d5e6f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": false
}

Some endpoints page with their own parameter, such as page or continuationToken, instead of cursor. Their reference pages name it. The full loop is on Pagination.

Idempotent requests

Send an Idempotency-Key header to make a call safe to retry. Use a fresh UUID for each logical operation.

curl "https://api.insightsocial.app/v1/tiktok/profile?handle=khaby.lame" \
  -H "x-api-key: $INSIGHTSOCIAL_API_KEY" \
  -H "Idempotency-Key: c3f9d27e-81b4-4e06-a5d2-94be0f6c1a78"

• A replay returns idempotent_replay: true, charge_reason: "replay" and credits_used: 0.
• If the original call with the same key is still running, you get 409 IDEMPOTENCY_IN_PROGRESS with Retry-After. Wait, then send the same key again.
• Keys are scoped to your account.
• A key must be at most 255 characters of letters, digits, ., _, : or -. A key that does not fit is ignored, and the call runs as an ordinary request.

Force a fresh fetch

Repeat calls can be served from the shared cache (cached: true) or free as an owned re-read. To skip both and fetch live, send Cache-Control: no-cache, or add fresh=1 to the query:

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

A fresh fetch is always charged at the normal price. See Credits for ownership windows.

Next steps