Data availability

A successful response tells you what one endpoint returned for one request. It is not proof that nothing else exists on the source platform.

The excerpt below is illustrative, not a captured response. It contains each state your parser needs to handle:

{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile/videos",
  "data": {
    "items": [
      {
        "post": {
          "id": "7462093158820417811",
          "content": { "text": "Mission update" },
          "engagement": { "shares": null }
        }
      }
    ],
    "dropped": 1,
    "_warnings": ["Illustrative advisory message"]
  },
  "pagination": {
    "next_cursor": "is2.eyJ2IjoyLCJjIjoiNzM4In0",
    "has_more": true,
    "page_size": 1
  },
  "credits_used": 20,
  "credits_remaining": 9480,
  "request_id": "req_1a2b3c4d5e6f",
  "cached": false,
  "idempotent_replay": false,
  "charge_reason": "miss",
  "free_call": false
}

In this row, post.id and post.content.text hold values, and post.engagement.shares is present but null. An optional field such as post.ext.music_id is simply not in the object.

Public data only

InsightSocial returns data that anyone can see on the platform without logging in. Private accounts and content behind a login are out of scope.

What is public changes over time. A post can be edited or deleted, an account can go private, and a platform can stop showing a field. A successful call describes what the chosen endpoint could see at that moment, in that cache state.

Five states to tell apart

Warnings never turn a success into an error. For the envelope itself see Response schema. For how derived values end up as numbers or null, see Computed fields.

One page is not the whole set

A list page only proves what is on that page. Check data.dropped, then follow the top-level pagination object if the response has one.

Pass pagination.next_cursor back exactly as you received it (it starts with is2.) in the cursor parameter, and stop when pagination.has_more is false. Do not stop based on data.total. Some endpoints page with their own parameters, such as page or continuationToken; the endpoint's reference page lists them. The full loop is in Pagination.

Reaching the last page means you have every page the endpoint offered. It does not guarantee full history: endpoint depth, deletions and access restrictions can still leave gaps.

Order is not stable

A platform can return records in a different order from one request to the next. Do not use a row's position as an identifier, and do not assume page one always spans the same time window.

When an endpoint offers a sort parameter, use it. Store the IDs and timestamps from each row, and deduplicate across pages and runs when your workflow needs it.

Region, language and date filters

Filters and depth differ per endpoint. A region, language or date parameter on one search endpoint says nothing about any other endpoint on the same platform.

Check the endpoint's parameters before you design a query. If a filter is not listed, assume it is not applied. When you filter on your side, do it only on fields that are present and fit the decision.

For example, read the TikTok profile videos reference before you build on /v1/tiktok/profile/videos. It lists the parameters that endpoint accepts and the fields it returns.

Freshness and cache state

The body field cached tells you whether the response came from a recent fetch rather than a new one. A cached response costs 5 credits, or nothing when you already own that exact response (charge_reason: "owned"). A cache hit is never guaranteed.

When your decision needs a new fetch, send Cache-Control: no-cache or add fresh=1. The call is then charged at the endpoint's normal price. Details are in Caching.

A new fetch is fresher, not more complete. It still reflects only what the platform shows at that moment.

An empty result is never charged. See Credits.

Provenance and extension fields

Store platform, endpoint and request_id alongside the IDs and URLs you keep. They let you trace any stored record back to the call that produced it.

Fields under ext.* carry platform-specific details and the IDs you need to chain one endpoint into another. Treat every ext field as optional, and check the unified schema for its type and which platforms fill it.

New optional fields can appear in responses. Ignore fields you do not recognize instead of rejecting the response, and validate only the fields you actually use.

Pick the endpoint that fits the question

The endpoint you choose sets what you can see. A profile lookup, a post list, a keyword search and a comment list answer different questions, with different filters and depth.

Start from the question, then use Choosing endpoints to find the narrowest endpoint that returns the object, coverage and controls you need.

Checklist

Before relying on an endpoint, confirm that:

• It returns the object and fields your question needs.
• The records you expect are public.
• Its region, language, date, ordering and depth controls are documented for that endpoint.
• Your loop sends pagination.next_cursor back unchanged and stops on pagination.has_more.
• You read data.dropped on every page and log data._warnings.
• Your parser treats a value, null and an absent field as three different cases.
• Your freshness policy reads cached and budgets for fresh fetches at the normal price.
• Stored records keep their IDs plus request_id, platform and endpoint.
• Unknown fields are ignored, and the fields you use are validated.