Responses and data

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

{
  "data": {},
  "request_id": "req_8f3c9a2b1d4e6f70",
  "upstream_calls": 1,
  "meta": {
    "credits_charged": 1,
    "credits_remaining": 9999
  }
}

Field	Meaning
`data`	The requested resource payload
`request_id`	Unique trace identifier; include it in logs and support requests
`upstream_calls`	Number of billable source requests used to complete this API request
`meta.credits_charged`	Exact scraper credits charged for this response; this includes account-specific pricing
`meta.credits_remaining`	Account balance after the charge

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 43 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:

Platforms	`creator` value
TikTok, Instagram, LinkedIn	Lowercase handle or slug
X	Canonical-case handle
YouTube, Facebook	Display name, such as `Coca-Cola`, not necessarily the requested identifier

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. videoUrls lists every rendition the platform serves, keyed high, medium, low and watermarked. videoUrl is the best of these. On TikTok, high is the HEVC master upload and can be hundreds of megabytes, while medium is TikTok’s own play address at about 576x1024 and a few megabytes. Pick medium when you only need a preview-sized file, for example for transcription. The map is populated on TikTok listings and details and on Instagram and Facebook details. It is null elsewhere, including Instagram and Facebook listings. A key is null when that rendition does not exist.

Transcripts and comments

Every normalized single-post endpoint accepts these optional booleans:

Parameter	Default	Result field
`include_transcript`	`false`	`transcript`
`include_comments`	`false`	`topComments`

They do not add a separate SideShift credit charge.

Platform	Transcript	Top comments	Pin state
TikTok	Supported	Supported	`null` (not published)
YouTube	Supported	Supported	Supported
Facebook	Supported	Supported	`null` (not published)
Instagram	Normalized flag returns `null`; use the separate platform transcript operation	Supported; one page, newest first	`null` (not published)
Snapchat	Accepted; returns `null`	Accepted; returns `null`	Accepted; returns `null`
X	Accepted; returns `null`	Accepted; returns `null`	Accepted; returns `null`
LinkedIn	Accepted; returns `null`	Accepted; returns `null`	Accepted; returns `null`

curl -X POST https://app.sideshift.app/api/v1/scrape/tiktok/post \
  -H "x-api-key: $SIDESHIFT_SCRAPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@mrbeast/video/1234567890123456789",
    "include_transcript": true,
    "include_comments": true
  }'

Single-post responses always include transcript, topComments, and pinnedComments; they are null when not requested or unavailable. Listing responses omit all three keys. topComments is a sample, not the full thread, and its order says nothing about pins: a pinned comment can be missing from the sample, and the first entry is not necessarily pinned. Read pin state from these fields instead:

Field	`true` / non-empty	`false` / `[]`	`null`
`isPinned` on each comment	Pinned	Confirmed not pinned	Unknown on this platform
`pinnedComments` on the post	The pinned comments	Checked, and nothing is pinned	Not checked; do not conclude anything

A null never means “not pinned”. On YouTube, pinnedComments includes the pinned comment even when it has too few likes to appear in topComments.

Checking a YouTube pin

When you only need to know whether a video has a pinned comment, for example to confirm a creator pinned a required comment, call POST /scrape/youtube/pinned-comment instead of fetching the whole post. It costs your account’s post rate and accepts a watch URL, a Shorts URL, a youtu.be link, or a bare 11-character video id.

curl -X POST https://app.sideshift.app/api/v1/scrape/youtube/pinned-comment \
  -H "x-api-key: $SIDESHIFT_SCRAPER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/shorts/DGVUsw4-GIQ" }'

{
  "data": {
    "pin_status": "resolved",
    "has_pinned_comment": true,
    "pinned_comments": [
      {
        "id": "UgxmrxxkBD0XpnKeiCx4AaABAg",
        "author": "Lucasisurguy",
        "text": "The site I used to find her active dating app profile is called…",
        "likeCount": 153,
        "replyCount": 20,
        "timestamp": null,
        "isPinned": true,
        "isCreator": true
      }
    ],
    "comment_count": 2754
  },
  "request_id": "req_8f3c9a2b1d4e6f70",
  "upstream_calls": 1,
  "meta": { "credits_charged": 1, "credits_remaining": 9998 }
}

Read pin_status first. resolved with an empty pinned_comments means the video has no pinned comment. unavailable means the check could not run; pinned_comments and has_pinned_comment are null, and you should retry rather than conclude. isCreator is YouTube’s own flag that the channel owner wrote the comment, so you do not need to match the channel name against the comment author.

TikTok has a dedicated transcript operation with platform-specific options and output. Instagram transcripts are available only through the separate Instagram transcript operation. That Instagram request is slower and costs one additional credit, so call it only when you need the reel’s spoken content.

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.

Guides

Reference

Responses and data

Success envelope

Two data contracts

Normalized endpoints

Platform-specific operations

Normalized post fields

Media URLs

Transcripts and comments

Checking a YouTube pin

Missing values and zero

​Success envelope

​Two data contracts

​Normalized endpoints

​Platform-specific operations

​Normalized post fields

​Media URLs

​Transcripts and comments

​Checking a YouTube pin

​Pagination fields

​Missing values and zero

Success envelope

Two data contracts

Normalized endpoints

Platform-specific operations

Normalized post fields

Media URLs

Transcripts and comments

Checking a YouTube pin

Pagination fields

Missing values and zero