> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses and data

> Understand response envelopes, schemas, cursors, media URLs, transcripts, and comments.

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

```json theme={"system"}
{
  "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 source requests needed to complete this API request    |
| `meta.credits_charged`   | Credits charged for this response                                |
| `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 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](/scraper/platform-operations) 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.

<Warning>
  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.
</Warning>

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.

<Warning>
  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.
</Warning>

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:

| 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             |
| --------- | ------------------------ | ------------------------ |
| TikTok    | Supported                | Supported                |
| YouTube   | Supported                | Supported                |
| Facebook  | Supported                | Supported                |
| Instagram | Accepted; returns `null` | Accepted; returns `null` |
| Snapchat  | Accepted; returns `null` | Accepted; returns `null` |
| X         | Accepted; returns `null` | Accepted; returns `null` |
| LinkedIn  | Accepted; returns `null` | Accepted; returns `null` |

```bash theme={"system"}
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` and `topComments`; they are `null` when
not requested or unavailable. Listing responses omit both keys.

<Note>
  TikTok also has a dedicated [`transcript` operation](/scraper/platform-operations#post-/api/v1/scrape/tiktok/transcript)
  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.
</Note>

## 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.