Skip to main content
Every successful endpoint returns one outer envelope. The structure inside data depends on whether you called a normalized endpoint or a platform-specific operation.

​
Success envelope

​
Two data contracts

​
Normalized endpoints

The profile, posts, post, and TikTok audience resources use stable SideShift schemas. This is the right surface when one parser needs to work across platforms.
  • Profile responses expose username, display_name, and follower_count on all seven platforms. Source-dependent fields are omitted when unavailable.
  • Posts responses expose a posts array, a profile_pictures map, and an optional next_cursor.
  • Single-post responses expose one normalized post plus transcript and topComments.
  • Audience responses expose TikTok country distribution in audienceLocations.

​
Platform-specific operations

The 42 focused TikTok and Instagram operations preserve the documented platform field names and nesting inside data. Capitalization is significant: fields such as uniqueId, UserStoryStatus, strong_id__, and AIGCDescription are not renamed. Use the platform operations guide or generated endpoint reference as the contract for each operation. Do not parse a platform-specific payload as a normalized profile or post.

​
Normalized post fields

Metrics are cumulative totals as of the request time. uploadedAt is Unix time in seconds. id is the platform’s own stable post identifier.
Use platform plus id to store and deduplicate posts. Do not use postPage: on a single-post lookup it echoes the URL you supplied, so different valid URLs for the same post can produce different values.
The creator field is not equally normalized on every platform: Join creator records using the identifier you requested or a stable profile identifier, not creator alone.

​
Media URLs

On TikTok, Instagram, and Facebook, videoUrl and thumbnail can be signed URLs that expire within hours. Download media when you receive it if you need to retain it.
On TikTok photo posts, videoUrl can point to the post’s audio track. Check the HTTP Content-Type of the downloaded bytes before treating the file as video.
YouTube listings do not include a usable videoUrl. Call the single post endpoint when you need the temporary media URL for a specific video or Short.

​
Transcripts and comments

Every normalized single-post endpoint accepts these optional booleans: They do not add a separate SideShift credit charge.
Single-post responses always include transcript and topComments; they are null when not requested or unavailable. Listing responses omit both keys.
TikTok also has a dedicated transcript operation with platform-specific options and output. Use it when you need that richer contract; use include_transcript on post when you want one normalized post response.

​
Pagination fields

Normalized listing endpoints return next_cursor. Pass it back as cursor and stop when it is absent or empty. Cursors are opaque printable strings and can be large; store and return them verbatim. Platform-specific operations use the pagination field documented for that operation, including min_time, max_cursor, next_max_id, max_id, or a page number. Follow the operation’s has_more field instead of assuming that a short page is the last page.

​
Missing values and zero

  • A missing property means the source did not provide that field for the resource.
  • null means the field is part of the contract but no value was available.
  • Numeric 0 is a real returned value. Do not treat it as missing.
  • Some platform metrics are structurally unavailable in listings even when a single-post lookup can return them.
The generated API reference is the source of truth for field types and required fields.