# SocialScrape documentation (full text)

Generated from the same source as the API. Base URL https://api.socialscrape.io. Index: https://socialscrape.io/llms.txt.
189 endpoints. Pages marked draft are left out.


---

# SocialScrape documentation

URL: https://socialscrape.io/docs

SocialScrape is an API for public social media data. You send a `GET` request with your key and get back normalised JSON: the same field names for a profile, a post or a comment on every platform, and a `null` where a platform does not provide a field.

There are 189 endpoints across 34 platform and service groups. Every one follows the same rules, so what you learn on the first one works on the rest.

## Start here

- [Quickstart](/docs/quickstart): your first request in a few minutes.
- [Authentication](/docs/authentication): the `x-api-key` header, keys and teams.
- [Responses](/docs/responses): the envelope around every answer.
- [Credits and pricing](/docs/credits): what a request costs. Failures and cached repeats are free.
- [Errors](/docs/errors): every error code and whether to retry.

## Build with it

- [Pagination](/docs/pagination), [Caching](/docs/caching), [Rate limits](/docs/rate-limits).
- [Batch and jobs](/docs/batch-and-jobs): many requests in one call, and long requests that answer later.
- [AI transcription](/docs/ai-transcription): transcripts for media that has no captions.
- [Monitors and webhooks](/docs/webhooks): get new posts pushed to you, signed.
- [MCP](/docs/mcp) and [SDKs](/docs/sdks): use SocialScrape from an AI agent or from code.
- [Switching from ScrapeCreators](/docs/switching-from-scrapecreators): the paths and parameter names you already use keep working.

## The API reference

- [YouTube](/docs/api/youtube): 18 endpoints
- [TikTok](/docs/api/tiktok): 24 endpoints
- [Instagram](/docs/api/instagram): 15 endpoints
- [Bluesky](/docs/api/bluesky): 3 endpoints
- [Threads](/docs/api/threads): 5 endpoints
- [Truth Social](/docs/api/truthsocial): 3 endpoints
- [Pinterest](/docs/api/pinterest): 5 endpoints
- [Twitch](/docs/api/twitch): 5 endpoints
- [Kick](/docs/api/kick): 2 endpoints
- [Snapchat](/docs/api/snapchat): 3 endpoints
- [Linktree](/docs/api/linktree): 1 endpoint
- [Komi](/docs/api/komi): 1 endpoint
- [Pillar](/docs/api/pillar): 1 endpoint
- [Lnk.Bio](/docs/api/linkbio): 1 endpoint
- [Linkme](/docs/api/linkme): 1 endpoint
- [Creator contact details](/docs/api/creators): 2 endpoints
- [X (Twitter)](/docs/api/twitter): 7 endpoints
- [Facebook](/docs/api/facebook): 25 endpoints
- [Google](/docs/api/google): 3 endpoints
- [LinkedIn](/docs/api/linkedin): 7 endpoints
- [Amazon](/docs/api/amazon): 1 endpoint
- [Spotify](/docs/api/spotify): 7 endpoints
- [Apple Music](/docs/api/apple-music): 4 endpoints
- [SoundCloud](/docs/api/soundcloud): 3 endpoints
- [GitHub](/docs/api/github): 10 endpoints
- [Kwai](/docs/api/kwai): 3 endpoints
- [Rumble](/docs/api/rumble): 5 endpoints
- [Telegram](/docs/api/telegram): 3 endpoints
- [Cosmos](/docs/api/cosmos): 7 endpoints
- [Transcript from any URL](/docs/api/transcript): 1 endpoint
- [Account](/docs/api/account): 4 endpoints
- [Jobs](/docs/api/jobs): 1 endpoint
- [Batch](/docs/api/batch): 1 endpoint
- [Monitors](/docs/api/monitors): 7 endpoints

Browse the [full API reference](/docs/api), or read the [data models](/docs/api/models).

## What we serve

Public, logged-out data only. We never log in to a platform, never use fake accounts and never return anything a visitor without an account could not see. Content a platform hides behind a login comes back as the `private` or `age_restricted` error. The rules for using the data are in the [acceptable use policy](/acceptable-use); to have your own data removed, see [takedown and opt-out](/takedown).


---

# Quickstart

URL: https://socialscrape.io/docs/quickstart

You need an API key. Sign up at [socialscrape.io](https://socialscrape.io) and open the [dashboard](https://socialscrape.io/app): new accounts get 100 free credits, once, with no card. Create a key there and keep it somewhere safe; it is shown once.

Put the key in an environment variable so the examples below run as written:

```bash
export SOCIALSCRAPE_API_KEY="your key here"
```

## 1. Make a request

This calls [TikTok profile](/docs/api/tiktok/profile). It costs 1 credit.

### curl

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=khaby.lame"
```

### Python

```python
import os
import requests

params = {
    "handle": "khaby.lame",
}
res = requests.get(
    "https://api.socialscrape.io/v1/tiktok/profile",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    params=params,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])
```

### TypeScript

```typescript
const url = new URL("https://api.socialscrape.io/v1/tiktok/profile");
url.search = new URLSearchParams({
  "handle": "khaby.lame"
}).toString();
const res = await fetch(url, {
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! },
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}
```

## 2. Read the answer

```json
{
  "ok": true,
  "credits_charged": 1,
  "credits_remaining": 4999,
  "cached": false,
  "cached_at": null,
  "request_id": "req_7115b8735eb56e7912694547",
  "data": {
    "object": "profile",
    "platform": "tiktok",
    "id": "127905465618821121",
    "handle": "khaby.lame",
    "name": "Khabane lame",
    "headline": null,
    "url": "https://www.tiktok.com/@khaby.lame",
    "kind": "creator",
    "bio": "Se vuoi ridere sei nel posto giusto😎 If u wanna laugh u r in the right place😎",
    "avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-useast8-avt-0068-tx2/08987e23b94057953fd4f1738694bf5f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640&refresh_token=09620b70&x-expires=1793498400&x-signature=hw%2FPqIqA%2BljrQyBvlTT4x5JfKuQ%3D&t=4...",
    "banner_url": null,
    "verified": true,
    "is_private": false,
    "external_url": null,
    "links": null,
    "location": null,
    "category": null,
    "created_at": null,
    "stats": {
      "followers": 162967647,
      "following": 82,
      "posts": 1359,
      "likes": 2691641827,
      "views": null
    },
    "extra": {
      "comment_setting": 0,
      "download_setting": 0,
      "duet_setting": 0,
      "following_visible": true,
      "friends": 77,
      "is_commerce_user": false,
      "is_organization": false,
      "is_tiktok_seller": false,
      "language": "en",
      "sec_uid": "MS4wLjABAAAAwAg0rSzO65WQfz4RzQgGv2Xdv108BgPXhRrrmNVIHQZ9PO8-flwwRtEppYTS0OjA",
      "stitch_setting": 0
    }
  },
  "cursor": null,
  "has_more": null
}
```

This response is a sample. Your own will carry live values.

- `ok` is `true`. A failure has `ok: false` and an `error` object instead of `data`; see [Errors](/docs/errors).
- `credits_charged` is what this request cost, and `credits_remaining` what is left. A failed request charges `0`.
- `cached` is `false` because this was fetched fresh. See [Caching](/docs/caching) to reuse results for free.
- `request_id` identifies the request. Quote it when you write to support.
- `data` is the result, in a shape shared across platforms. See [Data models](/docs/api/models).

## 3. Go further

- Lists return a `cursor`. Pass it back to get the next page: [Pagination](/docs/pagination).
- Pass `trim=true` for a smaller response, or `raw=true` to also get the platform's original object.
- Look up many things at once with [batch](/docs/batch-and-jobs), or watch a profile with [monitors](/docs/webhooks).
- Browse the [API reference](/docs/api) for every endpoint and its parameters.
- Using an AI agent? See [MCP](/docs/mcp).


---

# Authentication and keys

URL: https://socialscrape.io/docs/authentication

Every request carries your key in the `x-api-key` header:

```bash
curl "https://api.socialscrape.io/v1/account/credits" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

A key is never accepted in the query string, so it cannot end up in a log or a browser history.

## Key format

Live keys look like `ss_live_` followed by 40 letters and digits. Test keys start with `ss_test_`. Treat both as passwords.

## Create, rotate and revoke

Keys belong to a [team](/docs/teams), not to a person, and are managed in the [dashboard](https://socialscrape.io/app).

- Give each key a name, one per app or environment, so you can see what uses it.
- The full key is shown **once**, when you create it. We store only a hash, so we cannot show it again; if you lose it, create a new one.
- The dashboard shows when each key was last used.
- To rotate a key, create the new one, deploy it, then revoke the old one. A team can hold up to 20 active keys.
- A revoked key stops working within seconds.

Owners and admins can create and revoke keys. Members can see key names but not make changes; see [Teams](/docs/teams).

## What a bad key returns

| Situation | Answer |
|---|---|
| Header missing, key malformed, unknown or revoked | `401` `unauthorized` |
| The key or its team is suspended | `403` `forbidden` |
| The team has too few credits | `402` `insufficient_credits` |

A missing, malformed and revoked key all answer the same way on purpose, so an error never tells a stranger which keys exist.

## Keep keys out of code

- Read the key from an environment variable or a secrets manager. Never commit it.
- Call the API from your server. A key in browser or mobile code is public.
- If a key leaks, revoke it in the dashboard first, then create a replacement.

## Agents that pay for themselves

An AI agent holding a key with no credits can buy a pack over HTTP, with no dashboard. See [Credits and pricing](/docs/credits).


---

# Responses and the envelope

URL: https://socialscrape.io/docs/responses

Every answer, success or failure, is JSON in the same envelope.

## Success

```json
{
  "ok": true,
  "credits_charged": 1,
  "credits_remaining": 4999,
  "cached": false,
  "cached_at": null,
  "request_id": "req_0123456789abcdef01234567",
  "data": { },
  "cursor": null,
  "has_more": null
}
```

| Field | Meaning |
|---|---|
| `ok` | `true` on success. |
| `credits_charged` | What this request cost. `0` for a cached repeat, a free call or a failure. |
| `credits_remaining` | The team's balance after the charge. |
| `cached`, `cached_at` | Whether the answer came from the cache and when it was first fetched. See [Caching](/docs/caching). |
| `request_id` | Unique per request. Also sent as the `x-request-id` response header. |
| `data` | The result: one object, or a `list` object for list endpoints. |
| `cursor`, `has_more` | Copies of `data.cursor` and `data.has_more` for list endpoints; `null` for single objects. See [Pagination](/docs/pagination). |
| `raw` | Only with `raw=true`: the platform's original object. |

## Failure

```json
{
  "ok": false,
  "error": { "code": "not_found", "message": "The platform says this profile does not exist.", "retryable": false },
  "credits_charged": 0,
  "request_id": "req_0123456789abcdef01234567"
}
```

Branch on `error.code` and `error.retryable`, never on the message. All codes are on the [Errors](/docs/errors) page. Failures are always free.

## One shape for every platform

Each kind of thing has one model, shared by all platforms: `Profile`, `Post` (videos, reels, tweets and pins are posts with a `type`), `Comment`, `Song`, `Album`, `Collection`, `Community`, `Transcript`, `Ad` and a few more. The same names mean the same thing everywhere: `id`, `url`, `platform`, `author`, `text`, `published_at` (ISO 8601), `duration_seconds`, `stats` and `media`. [Data models](/docs/api/models) lists every field.

- A field the platform does not provide is `null`. We never invent values, and never use `0` or `""` for unknown.
- Counts are integers. Times are ISO 8601 with a time zone.
- Details with no field of their own are in `extra`, a flat object per platform.

## Parameters every endpoint accepts

| Parameter | What it does |
|---|---|
| `cursor` | Opaque cursor from the previous page; pass it back unchanged. Also accepted as `continuationToken`, `continuation_token`, `next_max_id`, `max_id`, `max_cursor`, `min_time`, `after`, `page_token`, `pageToken`, `paginationToken`, `next_page_id`, `page`. (List endpoints only.) |
| `region` | Two-letter country code (ISO 3166-1) for results that vary by country. Also accepted as `country`, `geo`. (Endpoints whose results vary by country only.) |
| `trim` | Smaller response: drops null fields and `extra`. |
| `raw` | Also return the platform's original object as `raw`. |
| `max_age_days` | Serve a cached result fetched within this many days, for 0 credits. ScrapeCreators' `cache_max_age=7d` spelling is accepted too. Also accepted as `cache_max_age`. |

`trim=true` removes every `null` field and `extra`. `raw=true` adds the platform's original object next to `data`; `trim` and `raw` do not change the price or the cache entry.

## Headers

| Header | Meaning |
|---|---|
| `x-request-id` | The request id, also in the body. |
| `x-ratelimit-limit`, `x-ratelimit-remaining` | Your allowance; see [Rate limits](/docs/rate-limits). |
| `retry-after` | On `429` and `503`: seconds to wait before retrying. |
| `x-ignored-params` | Names of query parameters the endpoint does not use. Unknown parameters are ignored, not rejected. |
| `x-idempotent-replay` | `true` when an `Idempotency-Key` returned the first answer again; see [Batch and jobs](/docs/batch-and-jobs). |

## Versioning

Every path starts with `/v1`. When a platform changes in a way that breaks a response, the one endpoint affected ships a new version and the old one keeps running until it is retired with notice in the [changelog](/docs/changelog). Adding a field to a response is not a breaking change, so ignore fields you do not know.

Each endpoint page shows its status: **beta** (built and tested against recorded responses, shape may still gain fields) or **stable** (verified live and watched by a canary). Endpoints not built yet are not listed.


---

# Credits and pricing

URL: https://socialscrape.io/docs/credits

One credit pays for one successful, ordinary request. You pay only for answers you get.

| Request | Credits |
|---|---|
| A profile, one page of posts, one page of search results, one page of comments | 1 |
| A transcript from captions | 1 |
| An AI transcript (the media had no captions) | 1 up to 2 minutes of audio, then 1 per started minute |
| A cached repeat of something already fetched (`max_age_days`) | 0 |
| Any failure | 0 |
| Account, usage, job and monitor management calls | 0 |

Failures are free, cached repeats are free (see [Caching](/docs/caching)), and every account, usage, job and monitor-management call is free. Each [endpoint page](/docs/api) states its own cost.

## Packs: credits that never expire

Buy credits once and use them whenever. No subscription.

| Pack | Price | Credits | Per 1,000 |
|---|---|---|---|
| Starter | $15 | 5,000 | $3.00 |
| Builder | $49 | 20,000 | $2.45 |
| Pro | $149 | 75,000 | $1.99 |
| Scale | $399 | 250,000 | $1.60 |

## Monthly plans: a lower rate per credit

Monthly credits reset each month and do not roll over. Annual billing is 10 months for 12.

| Plan | Price | Credits a month | Per 1,000 |
|---|---|---|---|
| Starter | $15 a month | 6,500 | $2.31 |
| Builder | $49 a month | 26,000 | $1.88 |
| Pro | $149 a month | 100,000 | $1.49 |
| Scale | $399 a month | 330,000 | $1.21 |
| Enterprise | Custom | 1,000,000 or more |  |

## Free credits

New accounts get 100 credits once, with no card. The grant is one per person.

## How credits are spent

A team has two kinds of credits. **Plan credits** come with a monthly plan, are used first and expire at each reset. **Pack credits** come from packs (and from the free grant), and never expire. The balance in every response, `credits_remaining`, is the sum. Credits belong to the [team](/docs/teams), so everyone and every key on the team draws from one balance.

Credits are checked before a request runs and charged only when it succeeds, so concurrent requests cannot overdraw a balance. With too few credits a request answers `402` `insufficient_credits`.

## The rules behind the prices

Every endpoint names one pricing rule:

| Rule | What it charges | Endpoints |
|---|---|---|
| `free` | Free | 12 |
| `standard` | 1 credit per successful request (a profile, a post, one page of a list) | 165 |
| `transcript` | 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute | 11 |
| `batch` | The sum of each sub-request's charge | 1 |

AI transcription has its own scale; see [AI transcription](/docs/ai-transcription).

## Refunds and failed payments

- A pack that is entirely unused can be refunded in full within 14 days of purchase by the team owner. After that, or once any of it is spent, there are no refunds, because credits never expire.
- If a monthly payment fails, plan credits stay usable for 7 days. After that they expire and the team falls back to its pack credits and the free rate limit until a payment succeeds.
- Closing a team forfeits its remaining credits.

Prices are in US dollars. The [pricing page](/pricing) shows the current plans.

## Agents that buy credits themselves

An AI agent with an API key can top up without a dashboard or a human. When a request fails with `402` `insufficient_credits`, the response also carries:

- a `payment` object that lists each pack with a payment link tied to the team behind the key, so a person or a browsing agent can pay by card; and
- one `WWW-Authenticate: Payment` challenge per pack, in the Machine Payments Protocol, for agents that hold a Shared Payment Token from Stripe's Link agent wallet.

An agent that can pay repeats the same request with `Authorization: Payment <credential>` answering a challenge. We charge the card, add the pack's credits to the team and run the request; the successful response carries a `Payment-Receipt` header. Repeating a credential never charges twice. Card is the only payment method for agents today.


---

# Errors

URL: https://socialscrape.io/docs/errors

A failed request returns the failure envelope and **charges nothing**:

```json
{
  "ok": false,
  "error": { "code": "upstream_blocked", "message": "The platform blocked this fetch; retry (a fresh exit is used).", "retryable": true },
  "credits_charged": 0,
  "request_id": "req_0123456789abcdef01234567"
}
```

Branch on `error.code` and `error.retryable`. Messages are for people and can change; codes are stable. There are 21 codes, each with one HTTP status.

### Mistakes in the request

| Code | HTTP | Retry | Meaning |
|---|---|---|---|
| `invalid_params` | 400 | no | A parameter is missing, unknown or has the wrong type. |
| `unsupported_url` | 400 | no | The URL is not one this endpoint accepts (wrong platform or form). |
| `unauthorized` | 401 | no | The x-api-key header is missing or not a valid key. |
| `insufficient_credits` | 402 | no | The team behind the key has too few credits for this request. |
| `forbidden` | 403 | no | The key or team is suspended or revoked. |
| `rate_limited` | 429 | yes | Too many requests for this team's plan; wait for Retry-After. |
| `conflict` | 409 | no | This Idempotency-Key was already used with a different request. |

### The thing you asked for

| Code | HTTP | Retry | Meaning |
|---|---|---|---|
| `not_found` | 404 | no | The platform says this profile, post or item does not exist. |
| `private` | 403 | no | The content is private; only public, logged-out data is served. |
| `age_restricted` | 403 | no | The platform hides this content from logged-out visitors (age gate). |
| `removed` | 410 | no | The content existed but was deleted or taken down. |
| `unavailable_in_region` | 451 | no | The platform does not serve this content in the requested region. |
| `transcript_unavailable` | 404 | no | No captions exist and AI transcription is not possible for this media. |

### The platform failed

| Code | HTTP | Retry | Meaning |
|---|---|---|---|
| `upstream_rate_limited` | 503 | yes | The platform is rate limiting us; retry shortly. |
| `upstream_blocked` | 503 | yes | The platform blocked this fetch; retry (a fresh exit is used). |
| `upstream_error` | 502 | yes | The platform returned an error or the connection failed. |
| `upstream_changed` | 502 | no | The platform's response no longer parses; we are fixing it. |
| `upstream_timeout` | 504 | yes | The platform did not answer in time. |

### Our side

| Code | HTTP | Retry | Meaning |
|---|---|---|---|
| `overloaded` | 503 | yes | This endpoint's queue is full; retry with backoff. |
| `not_implemented` | 501 | no | This endpoint is declared but not built yet. |
| `internal` | 500 | yes | Something broke on our side; it is logged. |

## Retrying

Retry when `retryable` is `true`: wait for the `retry-after` header if present, otherwise back off exponentially with some jitter. Do not retry the rest; the same request will fail the same way.

```python
import random
import time

import requests


def get(url, headers, params, attempts=5):
    for attempt in range(attempts):
        res = requests.get(url, headers=headers, params=params, timeout=60)
        body = res.json()
        if body["ok"] or not body["error"]["retryable"]:
            return body
        wait = float(res.headers.get("retry-after", 2 ** attempt))
        time.sleep(wait + random.random())
    return body
```

```typescript
async function get(url: string, headers: Record<string, string>, attempts = 5) {
  let body: any;
  for (let attempt = 0; attempt < attempts; attempt++) {
    const res = await fetch(url, { headers });
    body = await res.json();
    if (body.ok || !body.error.retryable) return body;
    const wait = Number(res.headers.get("retry-after") ?? 2 ** attempt);
    await new Promise((r) => setTimeout(r, (wait + Math.random()) * 1000));
  }
  return body;
}
```

Retrying a failure costs nothing. Retrying a `POST` that may have succeeded needs an `Idempotency-Key`; see [Batch and jobs](/docs/batch-and-jobs).

## Where to look first

- `not_found`, `private`, `removed`: the item is not available to a logged-out visitor. Check the URL or handle in a browser, signed out.
- `unsupported_url`: you passed a URL from the wrong platform or an unrecognised form. The endpoint page lists the accepted hosts.
- `upstream_changed`: the platform changed and our parser no longer reads it. We are alerted automatically and fix it; it is not retryable until we do.
- `invalid_params`: the message names the parameter.

When you write to [support](mailto:support@socialscrape.io), include the `request_id`.


---

# Pagination and cursors

URL: https://socialscrape.io/docs/pagination

Every list endpoint returns one page of results with a `cursor` and `has_more`:

```json
{
  "ok": true,
  "data": { "object": "list", "items": [ ], "cursor": "eyJvIjoyNX0", "has_more": true },
  "cursor": "eyJvIjoyNX0",
  "has_more": true
}
```

The envelope and `data` carry the same two values. To get the next page, send the same request with `cursor` set to the value you received.

- Treat the cursor as an opaque string. Pass it back **unchanged**; do not parse, build or store it long term.
- `has_more: false` (and `cursor: null`) means you have everything.
- Each page costs its usual price (usually 1 credit), whatever its size. See [Credits](/docs/credits).
- Keep every other parameter the same. Changing `sort`, `region` or the search terms starts a new chain: drop the cursor.
- `limit` is an upper bound. A platform may return fewer items than you ask for and still have more; rely on `has_more`, not on the page size.

```python
import os
import requests

url = "https://api.socialscrape.io/v1/github/user/repositories"  # any list endpoint
headers = {"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]}
params = {"handle": "torvalds"}

items = []
while True:
    body = requests.get(url, headers=headers, params=params, timeout=60).json()
    if not body["ok"]:
        raise RuntimeError(body["error"]["code"])
    items += body["data"]["items"]
    if not body["has_more"]:
        break
    params["cursor"] = body["cursor"]
```

```typescript
const url = new URL("https://api.socialscrape.io/v1/github/user/repositories"); // any list endpoint
url.searchParams.set("handle", "torvalds");
const headers = { "x-api-key": process.env.SOCIALSCRAPE_API_KEY! };

const items: unknown[] = [];
for (;;) {
  const body = await (await fetch(url, { headers })).json();
  if (!body.ok) throw new Error(body.error.code);
  items.push(...body.data.items);
  if (!body.has_more) break;
  url.searchParams.set("cursor", body.cursor);
}
```

## Cursors from other APIs

If you are switching from another API, the old cursor parameter names are accepted as `cursor`: `continuationToken`, `continuation_token`, `next_max_id`, `max_id`, `max_cursor`, `min_time`, `after`, `page_token`, `pageToken`, `paginationToken`, `next_page_id`, `page`. The values are not portable: a cursor from another provider means nothing here, so restart each list from the first page.

## Cursors and cached pages

Pages obey `max_age_days` like any request. A cached page that is still fresh returns for free with the cursor that was current when it was fetched. See [Caching](/docs/caching).


---

# Caching and max_age_days

URL: https://socialscrape.io/docs/caching

Social data that was fetched recently rarely needs fetching again. Tell us how old an answer you will accept and a fresh-enough cached copy comes back for **0 credits**.

```bash
curl -G "https://api.socialscrape.io/v1/github/user" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds" \
  --data-urlencode "max_age_days=7"
```

- `max_age_days` takes a number from 0 to 30. Absent or `0` means "always fetch fresh".
- The ScrapeCreators spelling works too: `cache_max_age=7d`. Units are `d`, `h`, `m` and `s`, so `cache_max_age=12h` is half a day.
- A hit is marked `"cached": true` with `cached_at` set to when the data was first fetched, and `credits_charged` is `0`.
- A miss fetches fresh, charges normally, and stores the result for next time.

## What counts as the same request

The cache key is the endpoint plus its parameters. Presentation parameters do not matter: `trim`, `raw` and `max_age_days` itself read the same entry. A different `cursor`, `sort`, `region` or search term is a different request.

The cache is keyed by request, not by customer, so a repeat of something anyone fetched recently can be served from it.

## How long results are kept

Cached results live at most 30 days, and an endpoint may keep them for less (its page says how long). After that they are deleted. Nothing is served from the cache unless you ask for it with `max_age_days`.

Some endpoints are never cached, for example your own balance, usage and monitors.

## Removing data

If a person asks us to remove their data, we delete matching cached results and stop serving them: such a request answers `410` `removed`. See [takedown and opt-out](/takedown).


---

# Rate limits

URL: https://socialscrape.io/docs/rate-limits

Each team has a request allowance per minute that follows what the team pays for:

| What the team has | Requests a minute |
|---|---|
| Free credits only | 30 |
| Any paid pack | 300 |
| Starter monthly plan | 120 |
| Builder monthly plan | 300 |
| Pro monthly plan | 600 |
| Scale monthly plan | 1,200 |
| Enterprise | 3,000 |

Bursts are fine. You can spend a whole minute's allowance at once; what counts is the average over a short window. Requests we refuse do not count against you.

## Headers

Every answer includes:

- `x-ratelimit-limit`: the requests a minute your team's tier allows.
- `x-ratelimit-remaining`: what is left right now.

## When you hit the limit

The answer is `429` `rate_limited`, which is retryable and free, with a `retry-after` header holding the exact number of seconds to wait:

```json
{
  "ok": false,
  "error": { "code": "rate_limited", "message": "Too many requests for this team's plan; wait for Retry-After.", "retryable": true },
  "credits_charged": 0,
  "request_id": "req_0123456789abcdef01234567"
}
```

Wait for `retry-after`, then continue. The [retry helper](/docs/errors) already does this. Do not spread a burst over many keys: the limit is per team, not per key.

## Batching

A [batch](/docs/batch-and-jobs) of up to 100 requests runs concurrently on our side and saves round trips, but each item still counts toward the limit.

## More headroom

Plans raise the limit; see [Credits and pricing](/docs/credits). For sustained volume above the top tier, write to [support@socialscrape.io](mailto:support@socialscrape.io).


---

# Batch requests and jobs

URL: https://socialscrape.io/docs/batch-and-jobs

## Batch

`POST /v1/batch` runs up to 100 `GET` requests in one call. Each item names a path and its parameters, exactly as you would send them alone:

```bash
curl -X POST "https://api.socialscrape.io/v1/batch" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c55-9a39-2f4f0f6a1c01" \
  -d '{"requests":[
        {"path":"/v1/github/user","params":{"handle":"torvalds"}},
        {"path":"/v1/github/user","params":{"handle":"gaearon"}}
      ]}'
```

The answer has one full envelope per item, in order, in `data.results`, each with its own `request_id`, charge and status:

```json
{
  "ok": true,
  "credits_charged": 2,
  "data": {
    "object": "batch",
    "results": [
      { "path": "/v1/github/user", "status": 200, "response": { "ok": true, "credits_charged": 1, "data": { } } },
      { "path": "/v1/github/user", "status": 404, "response": { "ok": false, "error": { "code": "not_found" }, "credits_charged": 0 } }
    ]
  }
}
```

- The batch's `credits_charged` is the sum of its items'. Each item is priced and cached as if you had called it alone, so failures and cached repeats cost nothing.
- A failing item never fails the others. Check each item's `ok`.
- Items run concurrently on our side and each counts toward your [rate limit](/docs/rate-limits).
- Credits are held up front, so concurrent items cannot overdraw the balance.

See [Batch requests](/docs/api/batch/create) in the reference.

## Retrying safely: Idempotency-Key

Send an `Idempotency-Key` header on a `POST` you might retry (a network error leaves you not knowing if it ran). The same key with the same request returns the **first answer again**, with `x-idempotent-replay: true`, and charges nothing a second time. Keys are remembered for 24 hours.

- The same key with a different request answers `409` `conflict`.
- A retry that arrives while the first is still running answers a retryable `503`; wait and retry.
- Server errors, `429` and `402` answers are not stored, so they are safe to retry with the same key after you fix the cause.

Use a fresh random value (a UUID) per logical operation.

## Jobs: requests that answer later

Most requests answer in a second or two. A request still running after about 25 seconds (AI transcription of a long video, a slow platform) answers `202` instead, with a job:

```json
{
  "ok": true,
  "credits_charged": 0,
  "credits_remaining": 5000,
  "cached": false,
  "cached_at": null,
  "request_id": "req_0123456789abcdef01234567",
  "data": {
    "object": "job",
    "job_id": "job_0123456789abcdef01234567",
    "status": "running",
    "poll_url": "https://api.socialscrape.io/v1/jobs/job_0123456789abcdef01234567"
  }
}
```

Poll `data.poll_url` with your key. Polling is free. While the job runs you get the same `202`; when it finishes you get the final envelope with the result and the charge, once. A failed job returns its error with `credits_charged: 0`. Job results are kept for 24 hours.

```python
import os
import time
import requests

headers = {"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]}
res = requests.get("https://api.socialscrape.io/v1/transcript", headers=headers, params={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}, timeout=60)

while res.status_code == 202:
    time.sleep(3)
    res = requests.get(res.json()["data"]["poll_url"], headers=headers, timeout=60)

body = res.json()
```

Look up a job by id with [Job result](/docs/api/jobs/get).


---

# AI transcription

URL: https://socialscrape.io/docs/ai-transcription

Transcript endpoints return the platform's own captions when the media has them. When it does not, SocialScrape can transcribe the audio for you, so a transcript request does not dead-end on "no captions".

## How it works

1. We look for captions first. If we find them, you get them: `source` is `captions` or `auto_captions` and the price is 1 credit.
2. If there are none, we transcribe the audio on our own GPUs and return the text with `source: "ai"`, a `language`, and timed `segments`.

```json
{
  "object": "transcript",
  "platform": "youtube",
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "source": "ai",
  "duration_seconds": 213.0,
  "text": "...",
  "segments": [ { "start": 0.0, "end": 4.0, "text": "..." } ]
}
```

Always check `source` if the difference between captions and machine transcription matters to you.

## What it costs

Captions cost 1 credit. AI transcription costs 1 credit for up to 2 minutes of audio, then 1 more credit for each started minute after that. You pay only when the transcript is delivered; a failed transcription is free.

| Audio length | Credits |
|---|---|
| Captions (any length) | 1 |
| 30 seconds | 1 |
| 2 minutes | 1 |
| 2 minutes 1 second | 2 |
| 3 minutes | 2 |
| 10 minutes | 9 |
| 30 minutes | 29 |
| 1 hour | 59 |
| 2 hours | 119 |

Cached repeats are free like any request, so fetching a transcript you already paid for again with [`max_age_days`](/docs/caching) costs nothing.

## Turn it off

These transcript endpoints take `ai_fallback=false`: [Kick clip transcript](/docs/api/kick/clip-transcript), [TikTok video transcript](/docs/api/tiktok/video-transcript), [Twitch clip transcript](/docs/api/twitch/clip-transcript). With it, the endpoint returns nothing instead of transcribing, and charges nothing. ScrapeCreators' `use_ai_as_fallback` is accepted as the same parameter.

## Time and long media

Short clips finish within the normal request time. Long media can take minutes. A request still running after about 25 seconds answers `202` with a job to poll; see [Batch and jobs](/docs/batch-and-jobs). Poll rather than holding a connection open.

Our own transcription capacity is shared and limited, by design:

- If the lane is busy or the daily allowance for your team is used up, the request fails with `overloaded` (retryable, free). Retry with backoff.
- Media longer than about 4 hours is refused with `transcript_unavailable`.
- `transcript_unavailable` also covers media with no speech or no audio track.

## Any URL

[Transcript from any video URL](/docs/api/transcript/from-url) takes a video URL from any supported platform, picks the right endpoint and returns the same result at the same price and from the same cache.

```bash
curl -G "https://api.socialscrape.io/v1/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

## Endpoints that return transcripts

- [YouTube video transcript](/docs/api/youtube/video-transcript) (`GET /v1/youtube/video/transcript`)
- [TikTok video transcript](/docs/api/tiktok/video-transcript) (`GET /v1/tiktok/video/transcript`)
- [Instagram reel transcript](/docs/api/instagram/post-transcript) (`GET /v1/instagram/post/transcript`)
- [Twitch clip transcript](/docs/api/twitch/clip-transcript) (`GET /v1/twitch/clip/transcript`)
- [Kick clip transcript](/docs/api/kick/clip-transcript) (`GET /v1/kick/clip/transcript`)
- [Facebook Ad Library ad transcript](/docs/api/facebook/ad-library-ad-transcript) (`GET /v1/facebook/ad-library/ad/transcript`)
- [X video transcript](/docs/api/twitter/tweet-transcript) (`GET /v1/twitter/tweet/transcript`)
- [Facebook video transcript](/docs/api/facebook/post-transcript) (`GET /v1/facebook/post/transcript`)
- [LinkedIn post video transcript](/docs/api/linkedin/post-transcript) (`GET /v1/linkedin/post/transcript`)
- [Rumble video transcript](/docs/api/rumble/video-transcript) (`GET /v1/rumble/video/transcript`)
- [Transcript from any video URL](/docs/api/transcript/from-url) (`GET /v1/transcript`)


---

# Monitors and webhooks

URL: https://socialscrape.io/docs/webhooks

A monitor watches a list endpoint (a profile's posts, a search, a channel's videos) on a schedule and sends **new items** to your webhook. You do not poll, and you pay only for the checks.

## Create a monitor

```bash
curl -X POST "https://api.socialscrape.io/v1/monitors" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
        "endpoint": "/v1/github/user/repositories",
        "params": { "handle": "torvalds" },
        "interval_minutes": 60,
        "webhook_url": "https://example.com/hooks/socialscrape"
      }'
```

The answer contains a `webhook_secret` (`whsec_...`). **It is shown once**; store it to verify deliveries. See [Create a monitor](/docs/api/monitors/create).

- `endpoint` is the path of any list endpoint. Parameters are that endpoint's own, with the same names and aliases. A monitor always reads the first page, fresh, so `cursor`, `max_age_days`, `raw` and `trim` are not allowed.
- `interval_minutes` runs from 15 to 1440 (one day); the default is 60.
- `webhook_url` must be an `https` URL on a public address. Private and internal addresses are refused.
- A team can have 100 monitors.

## How checks are billed

Each check is charged exactly like a request of your own to that endpoint, from the team's credits; a failed check costs nothing. If the team is out of credits the check is skipped and tried again at the next interval; the monitor is not deleted. The first check only records a baseline, so a new monitor never floods you with old items.

If the platform keeps failing, the interval stretches (doubling per failure, up to one day). A monitor whose target is gone for good (a deleted profile) is paused, with `active: false` and the reason in `last_error`.

## What you receive

Each new batch of items is one event, sent as a `POST` with a JSON body:

```json
{
  "object": "monitor_event",
  "id": "evt_0123456789abcdef",
  "monitor_id": "mon_0123456789abcdef",
  "type": "new_items",
  "items": [ { "object": "repo", "platform": "github", "id": "2325298", "full_name": "torvalds/linux" } ],
  "created_at": "2026-10-29T15:00:02Z"
}
```

`items` are the same normalised objects the watched endpoint returns. [Monitor events](/docs/api/monitors/events) lists past events, the same ones the webhook delivers. Send yourself a signed `"type": "test"` event any time with [Send a test event](/docs/api/monitors/test).

Headers on every delivery:

| Header | Meaning |
|---|---|
| `SocialScrape-Event-Id` | The event id. The same id is never a new event, so use it to drop duplicates. |
| `SocialScrape-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>`. |
| `User-Agent` | `SocialScrape-Webhooks/1` |

## Verify the signature

Always verify before trusting a delivery. The signed string is the timestamp, a dot, then the **raw request body** exactly as received. The key is your `whsec_...` secret. Compute HMAC-SHA256, hex encode, compare to `v1` in constant time, and reject a timestamp older than 5 minutes.

Verify against the raw bytes, not a re-serialised copy of parsed JSON.

### Python

```python
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(secret: str, raw_body: bytes, header: str, now: int | None = None) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        timestamp = int(parts["t"])
        given = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs((now if now is not None else int(time.time())) - timestamp) > TOLERANCE_SECONDS:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, given)
```

With Flask or FastAPI, read `request.get_data()` or `await request.body()` for the raw body.

### Node.js

```javascript
const crypto = require("node:crypto");

const TOLERANCE_SECONDS = 300;

function verify(secret, rawBody, header, now = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split(/=(.*)/s).slice(0, 2)));
  const timestamp = Number(parts.t);
  const given = parts.v1;
  if (!Number.isInteger(timestamp) || typeof given !== "string") return false;
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(given);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

With Express, use `express.raw({ type: "application/json" })` on the webhook route so `req.body` is the raw `Buffer`.

## Respond and retry

Answer with any `2xx` within 10 seconds; we do not read your response body and we do not follow redirects. Anything else counts as a failed attempt and is retried, 6 attempts in all:

| Attempt | When |
|---|---|
| 1 | Immediately |
| 2 | 1 minute after the previous attempt |
| 3 | 5 minutes after the previous attempt |
| 4 | 30 minutes after the previous attempt |
| 5 | 2 hours after the previous attempt |
| 6 | 12 hours after the previous attempt |

If every attempt fails, the event is marked as a dead letter (also immediately if your endpoint answers `410 Gone`). Nothing is lost: see [Webhook delivery log](/docs/api/monitors/deliveries) for every attempt, and [Send an event again](/docs/api/monitors/redeliver) to start a fresh chain once your receiver is fixed.

Make your handler idempotent: respond quickly, queue the work, and deduplicate on the event id.

## Manage monitors

[List monitors](/docs/api/monitors/list) and [delete a monitor](/docs/api/monitors/delete) are free. Deleting stops all further checks.


---

# Teams

URL: https://socialscrape.io/docs/teams

Everything you buy or use belongs to a **team**, not to a person: the credit balance, the API keys, the usage history, the monitors and the billing. Every account starts with a team of one, and you can invite others to it.

- Every key on a team draws from the same credit balance.
- Requests are rate limited per team; see [Rate limits](/docs/rate-limits).
- Usage by key and by endpoint is in the [dashboard](https://socialscrape.io/app) and through [Request history](/docs/api/account/usage).

## Roles

There are three roles. The person who creates the team is its owner.

| Can | Owner | Admin | Member |
|---|---|---|---|
| See the team, members, usage and keys (names only) | yes | yes | yes |
| Create API keys | yes | yes |  |
| Revoke and rotate API keys | yes | yes |  |
| Buy packs and start a plan | yes | yes |  |
| Open the billing portal, change or cancel the plan | yes |  |  |
| Refund an unused pack | yes |  |  |
| Invite members | yes | yes |  |
| Invite admins | yes |  |  |
| Remove members (admins can remove members only) | yes | yes |  |
| Change roles | yes |  |  |
| Transfer ownership | yes |  |  |
| Delete the team | yes |  |  |

Admins can do the everyday work (keys, credits, inviting and removing members). Only the owner manages billing, refunds and roles, and can transfer ownership or delete the team. Owners can remove anyone except themselves; transfer ownership first.

## Invites

Owners and admins invite people by email from the dashboard. An invitee signs in with the invited address (email, Google or GitHub) and joins as the role they were invited with. Only the owner can invite admins.

## Keys

A team can hold up to 20 active keys, each with a name and a last-used time. See [Authentication](/docs/authentication) for rotating and revoking.

## Free credits

The 100 free credits are granted once per person, when they first sign up. Creating or joining more teams does not grant more, and disposable email domains do not qualify.

## Closing a team

Deleting a team revokes its keys, cancels its subscription and forfeits its remaining credits. Export what you need from your usage history first.


---

# Switching from ScrapeCreators

URL: https://socialscrape.io/docs/switching-from-scrapecreators

If you use ScrapeCreators today, most of your code keeps working. The request side is built to match: paths, parameter names, the `x-api-key` header and the `cache_max_age` spelling are all accepted. What changes is the host, the key, and the shape of the response.

## Move over in four steps

1. Change the base URL from `https://api.scrapecreators.com` to `https://api.socialscrape.io`.
2. Swap the key. The header is the same: `x-api-key`.
3. Keep your request paths and parameters. Most paths are identical. Where ScrapeCreators spells a path differently (44 endpoints today; the list is below), theirs is registered as an alias of ours and still works. Their parameter names are accepted too.
4. Update how you read the response. See the differences below.

```bash
# before
curl "https://api.scrapecreators.com/v1/youtube/channel-videos?handle=MrBeast&sort=popular" -H "x-api-key: $OLD_KEY"

# after
curl "https://api.socialscrape.io/v1/youtube/channel/videos?handle=MrBeast&sort=popular" -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

## What stays the same

- **Auth:** the `x-api-key` header.
- **Paths:** the same `/v1/...` style; where their path differs from ours (a different version or word), theirs still works. Table below.
- **Parameter names:** `username`, `user_id`, `sort_by`, `continuationToken` and the other names they use are accepted and mapped to ours. Table below.
- **Caching:** `cache_max_age=7d` works. We accept any age from 0 to 30 days in days, hours, minutes or seconds, not only fixed steps. See [Caching](/docs/caching).
- **Envelope names:** `credits_charged` and `credits_remaining`, and `cached` with `cached_at`, are the same.
- **Unknown parameters** are ignored, not rejected, and listed in the `x-ignored-params` response header. Parameters that only apply to their own billing, such as `download_media`, are simply ignored.

## What is different

**Responses are normalised.** ScrapeCreators passes each platform's raw JSON through, so a TikTok video has TikTok's field names and an Instagram post has Instagram's. SocialScrape returns one shape for every platform: a video, a reel and a tweet are all a `Post` with the same field names (`stats.likes`, `author.handle`, `published_at`). Your parsing gets simpler across platforms, but you will need to remap fields once. See [Data models](/docs/api/models). The platform's own fields we do not model are in `extra`, and `raw=true` adds the platform's original object next to `data` (its contents are the platform's, so it is not promised to equal ScrapeCreators' payload byte for byte).

**The data sits in `data`.** The result is in `data`, with `ok` first. Lists are `data.items` with `data.cursor` and `data.has_more`.

**Errors have codes.** A failure is `{ "ok": false, "error": { "code", "message", "retryable" } }` with `credits_charged: 0`. See [Errors](/docs/errors).

**Cursors are our own.** The cursor parameter names are accepted, but a cursor from ScrapeCreators means nothing here: restart lists from the first page. See [Pagination](/docs/pagination).

**Prices are flat.** Every request is its normal price. There are no surcharges for downloading media, including replies or fetching ad details, and no extra price for creator contact tools. AI transcription is priced by length; see [AI transcription](/docs/ai-transcription). Packs never expire; see [Credits and pricing](/docs/credits).

**Some things are not offered.** Logged-in data is never served, and we do not offer TikTok audience demographics, which come from non-public creator analytics.

**Some things are extra.** [Monitors and webhooks](/docs/webhooks), [batch](/docs/batch-and-jobs), AI transcription on every platform that has a transcript endpoint, and a [transcript from any URL](/docs/api/transcript/from-url).

## Paths that differ

Both columns work against `https://api.socialscrape.io`. Every path not listed here is the same on both sides.

| ScrapeCreators path | SocialScrape path |
|---|---|
| `GET /v1/account/credit-balance` | [`GET /v1/account/credits`](/docs/api/account/credits) |
| `GET /v1/account/get-api-usage` | [`GET /v1/account/usage`](/docs/api/account/usage) |
| `GET /v1/account/get-daily-usage-count` | [`GET /v1/account/usage/daily`](/docs/api/account/usage-daily) |
| `GET /v1/account/get-most-used-routes` | [`GET /v1/account/usage/routes`](/docs/api/account/usage-routes) |
| `GET /v1/bluesky/user/posts` | [`GET /v1/bluesky/profile/posts`](/docs/api/bluesky/profile-posts) |
| `GET /v1/cosmos/cluster/posts` | [`GET /v1/cosmos/collection/posts`](/docs/api/cosmos/collection-posts) |
| `GET /v1/cosmos/cluster` | [`GET /v1/cosmos/collection`](/docs/api/cosmos/collection) |
| `GET /v1/cosmos/user/clusters` | [`GET /v1/cosmos/profile/collections`](/docs/api/cosmos/profile-collections) |
| `GET /v1/cosmos/user/posts` | [`GET /v1/cosmos/profile/posts`](/docs/api/cosmos/profile-posts) |
| `GET /v1/facebook/adLibrary/ad/transcript` | [`GET /v1/facebook/ad-library/ad/transcript`](/docs/api/facebook/ad-library-ad-transcript) |
| `GET /v1/facebook/adLibrary/ad` | [`GET /v1/facebook/ad-library/ad`](/docs/api/facebook/ad-library-ad) |
| `GET /v1/facebook/adLibrary/company/ads` | [`GET /v1/facebook/ad-library/company/ads`](/docs/api/facebook/ad-library-company-ads) |
| `GET /v1/facebook/adLibrary/search/ads` | [`GET /v1/facebook/ad-library/search`](/docs/api/facebook/ad-library-search) |
| `GET /v1/facebook/adLibrary/search/companies` | [`GET /v1/facebook/ad-library/search/companies`](/docs/api/facebook/ad-library-search-companies) |
| `GET /v1/facebook/event/details` | [`GET /v1/facebook/event`](/docs/api/facebook/event) |
| `GET /v1/find-creator-emails` | [`GET /v1/creators/emails`](/docs/api/creators/emails) |
| `GET /v1/find-social-profiles` | [`GET /v1/creators/social-profiles`](/docs/api/creators/social-profiles) |
| `GET /v1/google/adLibrary/advertisers/search` | [`GET /v1/google/ad-library/advertisers/search`](/docs/api/google/ad-library-advertisers-search) |
| `GET /v1/google/ad` | [`GET /v1/google/ad-library/ad`](/docs/api/google/ad-library-ad) |
| `GET /v1/google/company/ads` | [`GET /v1/google/ad-library/company/ads`](/docs/api/google/ad-library-company-ads) |
| `GET /v1/instagram/audio/reels` | [`GET /v1/instagram/song/reels`](/docs/api/instagram/song-reels) |
| `GET /v1/instagram/user/embed` | [`GET /v1/instagram/profile/embed`](/docs/api/instagram/profile-embed) |
| `GET /v1/instagram/user/highlight/detail` | [`GET /v1/instagram/highlight`](/docs/api/instagram/highlight) |
| `GET /v1/instagram/user/highlights` | [`GET /v1/instagram/profile/highlights`](/docs/api/instagram/profile-highlights) |
| `GET /v1/instagram/user/reels` | [`GET /v1/instagram/profile/reels`](/docs/api/instagram/profile-reels) |
| `GET /v1/kwai/user/posts` | [`GET /v1/kwai/profile/posts`](/docs/api/kwai/profile-posts) |
| `GET /v1/linkedin/ad` | [`GET /v1/linkedin/ad-library/ad`](/docs/api/linkedin/ad-library-ad) |
| `GET /v1/linkedin/ads/search` | [`GET /v1/linkedin/ad-library/search`](/docs/api/linkedin/ad-library-search) |
| `GET /v1/pinterest/user/boards` | [`GET /v1/pinterest/profile/boards`](/docs/api/pinterest/profile-boards) |
| `GET /v1/threads/user/posts` | [`GET /v1/threads/profile/posts`](/docs/api/threads/profile-posts) |
| `GET /v1/tiktok/get-trending-feed` | [`GET /v1/tiktok/trending`](/docs/api/tiktok/trending) |
| `GET /v1/tiktok/product` | [`GET /v1/tiktok/shop/product`](/docs/api/tiktok/shop-product) |
| `GET /v1/tiktok/user/live` | [`GET /v1/tiktok/profile/live`](/docs/api/tiktok/profile-live) |
| `GET /v1/truthsocial/user/posts` | [`GET /v1/truthsocial/profile/posts`](/docs/api/truthsocial/profile-posts) |
| `GET /v1/twitter/user-tweets` | [`GET /v1/twitter/profile/tweets`](/docs/api/twitter/profile-tweets) |
| `GET /v1/youtube/channel-videos` | [`GET /v1/youtube/channel/videos`](/docs/api/youtube/channel-videos) |
| `GET /v2/instagram/media/transcript` | [`GET /v1/instagram/post/transcript`](/docs/api/instagram/post-transcript) |
| `GET /v2/instagram/post/comments` | [`GET /v1/instagram/post/comments`](/docs/api/instagram/post-comments) |
| `GET /v2/instagram/reels/search` | [`GET /v1/instagram/search/reels`](/docs/api/instagram/search-reels) |
| `GET /v2/instagram/user/posts` | [`GET /v1/instagram/profile/posts`](/docs/api/instagram/profile-posts) |
| `GET /v2/tiktok/video` | [`GET /v1/tiktok/video`](/docs/api/tiktok/video) |
| `GET /v3/tiktok/profile/videos` | [`GET /v1/tiktok/profile/videos`](/docs/api/tiktok/profile-videos) |
| `POST /v1/facebook/adLibrary/company/ads` | [`POST /v1/facebook/ad-library/company/ads`](/docs/api/facebook/ad-library-company-ads-post) |
| `POST /v1/facebook/adLibrary/search/ads` | [`POST /v1/facebook/ad-library/search`](/docs/api/facebook/ad-library-search-post) |

## Parameter names

Their name on the left is accepted wherever the endpoint has the parameter on the right.

| Their parameter | Ours | Endpoints |
|---|---|---|
| `use_ai_as_fallback` | `ai_fallback` | 3 |
| `cid` | `comment_id` | 1 |
| `commentId` | `comment_id` | 3 |
| `company_name` | `company` | 1 |
| `companyId` | `company_id` | 1 |
| `companyName` | `company_name` | 2 |
| `after` | `cursor` | 104 |
| `continuationToken` | `cursor` | 104 |
| `continuation_token` | `cursor` | 104 |
| `max_cursor` | `cursor` | 104 |
| `max_id` | `cursor` | 104 |
| `min_time` | `cursor` | 104 |
| `next_max_id` | `cursor` | 104 |
| `next_page_id` | `cursor` | 104 |
| `page` | `cursor` | 104 |
| `pageToken` | `cursor` | 104 |
| `page_token` | `cursor` | 104 |
| `paginationToken` | `cursor` | 104 |
| `datePosted` | `date_posted` | 1 |
| `endDate` | `end_date` | 2 |
| `endTime` | `end_time` | 1 |
| `login` | `handle` | 7 |
| `screen_name` | `handle` | 2 |
| `user_id` | `handle` | 1 |
| `username` | `handle` | 53 |
| `adId` | `id` | 4 |
| `ad_id` | `id` | 4 |
| `advertiserId` | `id` | 1 |
| `advertiser_id` | `id` | 1 |
| `audioId` | `id` | 1 |
| `audio_id` | `id` | 1 |
| `aweme_id` | `id` | 4 |
| `channelId` | `id` | 7 |
| `channel_id` | `id` | 7 |
| `clipId` | `id` | 2 |
| `community_id` | `id` | 2 |
| `event_id` | `id` | 1 |
| `group_id` | `id` | 2 |
| `highlight_id` | `id` | 1 |
| `item_id` | `id` | 1 |
| `media_id` | `id` | 3 |
| `music_id` | `id` | 2 |
| `pageId` | `id` | 3 |
| `page_id` | `id` | 3 |
| `playlistId` | `id` | 1 |
| `playlist_id` | `id` | 1 |
| `product_id` | `id` | 2 |
| `room_id` | `id` | 1 |
| `secUid` | `id` | 2 |
| `sec_uid` | `id` | 2 |
| `shortcode` | `id` | 3 |
| `tweet_id` | `id` | 2 |
| `userId` | `id` | 4 |
| `user_id` | `id` | 7 |
| `videoId` | `id` | 5 |
| `video_id` | `id` | 9 |
| `includeExtras` | `include_extras` | 3 |
| `lang` | `language` | 9 |
| `latitude` | `lat` | 1 |
| `count` | `limit` | 1 |
| `longitude` | `lng` | 1 |
| `search_type` | `match` | 2 |
| `cache_max_age` | `max_age_days` | 176 |
| `keyword` | `query` | 28 |
| `q` | `query` | 28 |
| `radius` | `radius_km` | 1 |
| `country` | `region` | 28 |
| `geo` | `region` | 28 |
| `full_name` | `repo` | 1 |
| `order` | `sort` | 18 |
| `sortBy` | `sort` | 18 |
| `sort_by` | `sort` | 18 |
| `startDate` | `start_date` | 2 |
| `startTime` | `start_time` | 1 |
| `active_status` | `status` | 4 |
| `statusCode` | `status` | 1 |
| `status_code` | `status` | 1 |
| `filter` | `type` | 2 |
| `filter_by` | `type` | 1 |
| `uploadDate` | `upload_date` | 1 |

## Parameter values

Where a value is spelled differently, theirs is accepted and mapped to ours before validation.

| Endpoint | Parameter | Their value | Our value |
|---|---|---|---|
| [YouTube channel videos](/docs/api/youtube/channel-videos) | `sort` | `newest` | `latest` |
| [YouTube channel Shorts](/docs/api/youtube/channel-shorts) | `sort` | `newest` | `latest` |
| [YouTube search](/docs/api/youtube/search) | `type` | `videos` | `video` |
| [YouTube search](/docs/api/youtube/search) | `type` | `shorts` | `short` |
| [YouTube search](/docs/api/youtube/search) | `type` | `channels` | `channel` |
| [YouTube search](/docs/api/youtube/search) | `type` | `playlists` | `playlist` |
| [YouTube search](/docs/api/youtube/search) | `upload_date` | `this_week` | `week` |
| [YouTube search](/docs/api/youtube/search) | `upload_date` | `this_month` | `month` |
| [YouTube search](/docs/api/youtube/search) | `upload_date` | `this_year` | `year` |
| [YouTube search](/docs/api/youtube/search) | `duration` | `under_3_min` | `short` |
| [YouTube search](/docs/api/youtube/search) | `duration` | `between_3_and_20_min` | `medium` |
| [YouTube search](/docs/api/youtube/search) | `duration` | `over_20_min` | `long` |
| [YouTube videos by hashtag](/docs/api/youtube/search-hashtag) | `type` | `shorts` | `short` |
| [YouTube video comments](/docs/api/youtube/video-comments) | `sort` | `newest` | `latest` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `sort` | `most-liked` | `likes` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `sort` | `date-posted` | `latest` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `yesterday` | `day` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `this-week` | `week` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `this-month` | `month` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `last-3-months` | `three_months` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `last-6-months` | `six_months` |
| [TikTok video search](/docs/api/tiktok/search-keyword) | `date_posted` | `all-time` | `any` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `yesterday` | `day` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `this-week` | `week` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `this-month` | `month` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `last-3-months` | `three_months` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `last-6-months` | `six_months` |
| [TikTok top search](/docs/api/tiktok/search-top) | `publish_time` | `all-time` | `any` |
| [TikTok top search](/docs/api/tiktok/search-top) | `sort` | `most-liked` | `likes` |
| [TikTok top search](/docs/api/tiktok/search-top) | `sort` | `date-posted` | `latest` |
| [Instagram reel search](/docs/api/instagram/search-reels) | `date_posted` | `last-week` | `week` |
| [Instagram reel search](/docs/api/instagram/search-reels) | `date_posted` | `last-month` | `month` |
| [Instagram reel search](/docs/api/instagram/search-reels) | `date_posted` | `last-year` | `year` |
| [Twitch user videos](/docs/api/twitch/user-videos) | `type` | `HIGHLIGHT` | `highlight` |
| [Twitch user videos](/docs/api/twitch/user-videos) | `type` | `ARCHIVE` | `archive` |
| [Twitch user videos](/docs/api/twitch/user-videos) | `type` | `UPLOAD` | `upload` |
| [Twitch user videos](/docs/api/twitch/user-videos) | `sort` | `TIME` | `time` |
| [Twitch user videos](/docs/api/twitch/user-videos) | `sort` | `VIEWS` | `views` |
| [Find a creator's other social profiles](/docs/api/creators/social-profiles) | `platform` | `x` | `twitter` |
| [Find a creator's public emails](/docs/api/creators/emails) | `platform` | `x` | `twitter` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `sort` | `total_impressions` | `impressions` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `sort` | `relevancy_monthly_grouped` | `newest` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `match` | `keyword_unordered` | `any_words` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `match` | `keyword_exact_phrase` | `exact_phrase` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `ad_type` | `political_and_issue_ads` | `political` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `status` | `ACTIVE` | `active` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `status` | `INACTIVE` | `inactive` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `status` | `ALL` | `all` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `ALL` | `all` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `IMAGE` | `image` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `VIDEO` | `video` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `MEME` | `meme` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `IMAGE_AND_MEME` | `image_and_meme` |
| [Facebook Ad Library search](/docs/api/facebook/ad-library-search) | `media_type` | `NONE` | `none` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `sort` | `total_impressions` | `impressions` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `sort` | `relevancy_monthly_grouped` | `newest` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `match` | `keyword_unordered` | `any_words` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `match` | `keyword_exact_phrase` | `exact_phrase` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `ad_type` | `political_and_issue_ads` | `political` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `status` | `ACTIVE` | `active` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `status` | `INACTIVE` | `inactive` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `status` | `ALL` | `all` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `ALL` | `all` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `IMAGE` | `image` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `VIDEO` | `video` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `MEME` | `meme` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `IMAGE_AND_MEME` | `image_and_meme` |
| [Facebook Ad Library search (POST body)](/docs/api/facebook/ad-library-search-post) | `media_type` | `NONE` | `none` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `status` | `ACTIVE` | `active` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `status` | `INACTIVE` | `inactive` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `status` | `ALL` | `all` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `ALL` | `all` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `IMAGE` | `image` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `VIDEO` | `video` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `MEME` | `meme` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `IMAGE_AND_MEME` | `image_and_meme` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `media_type` | `NONE` | `none` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `sort` | `total_impressions` | `impressions` |
| [Facebook Ad Library ads by page](/docs/api/facebook/ad-library-company-ads) | `sort` | `relevancy_monthly_grouped` | `newest` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `status` | `ACTIVE` | `active` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `status` | `INACTIVE` | `inactive` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `status` | `ALL` | `all` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `ALL` | `all` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `IMAGE` | `image` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `VIDEO` | `video` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `MEME` | `meme` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `IMAGE_AND_MEME` | `image_and_meme` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `media_type` | `NONE` | `none` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `sort` | `total_impressions` | `impressions` |
| [Facebook Ad Library ads by page (POST body)](/docs/api/facebook/ad-library-company-ads-post) | `sort` | `relevancy_monthly_grouped` | `newest` |
| [Facebook public group posts](/docs/api/facebook/group-posts) | `sort` | `TOP_POSTS` | `top` |
| [Facebook public group posts](/docs/api/facebook/group-posts) | `sort` | `RECENT_ACTIVITY` | `recent_activity` |
| [Facebook public group posts](/docs/api/facebook/group-posts) | `sort` | `CHRONOLOGICAL` | `chronological` |
| [Facebook public group posts](/docs/api/facebook/group-posts) | `sort` | `CHRONOLOGICAL_LISTINGS` | `chronological_listings` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `sort` | `suggested` | `relevance` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `sort` | `distance_ascend` | `distance` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `sort` | `creation_time_descend` | `newest` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `sort` | `price_ascend` | `price_low` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `sort` | `price_descend` | `price_high` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `1` | `day` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `7` | `week` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `30` | `month` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `last_24_hours` | `day` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `last_7_days` | `week` |
| [Facebook Marketplace search](/docs/api/facebook/marketplace-search) | `date_listed` | `last_30_days` | `month` |
| [Spotify search](/docs/api/spotify/search) | `type` | `podcast` | `show` |
| [Spotify search](/docs/api/spotify/search) | `type` | `podcasts` | `show` |
| [Spotify search](/docs/api/spotify/search) | `type` | `tracks` | `track` |
| [Spotify search](/docs/api/spotify/search) | `type` | `albums` | `album` |
| [Spotify search](/docs/api/spotify/search) | `type` | `artists` | `artist` |
| [Spotify search](/docs/api/spotify/search) | `type` | `playlists` | `playlist` |
| [Spotify search](/docs/api/spotify/search) | `type` | `episodes` | `episode` |
| [Spotify search](/docs/api/spotify/search) | `type` | `audiobooks` | `audiobook` |


---

# API reference

URL: https://socialscrape.io/docs/api

Base URL `https://api.socialscrape.io`. Everything lives under `/v1`. Send your key in the `x-api-key` header; see [Authentication](/docs/authentication).

189 endpoints across 34 platform and service groups:

| Platform | Endpoints | Includes |
|---|---|---|
| [YouTube](/docs/api/youtube) | 18 | YouTube channel details; YouTube channel videos; Search inside a YouTube channel |
| [TikTok](/docs/api/tiktok) | 24 | TikTok profile; TikTok profile videos; TikTok collection videos |
| [Instagram](/docs/api/instagram) | 15 | Instagram profile; Instagram profile by user id; Instagram profile post count |
| [Bluesky](/docs/api/bluesky) | 3 | Bluesky profile; Bluesky profile posts; Bluesky post |
| [Threads](/docs/api/threads) | 5 | Threads profile; Threads profile posts; Threads post |
| [Truth Social](/docs/api/truthsocial) | 3 | Truth Social profile; Truth Social profile posts; Truth Social post |
| [Pinterest](/docs/api/pinterest) | 5 | Pinterest pin search; Pinterest pin; Pinterest user boards |
| [Twitch](/docs/api/twitch) | 5 | Twitch channel; Twitch user videos; Twitch stream schedule |
| [Kick](/docs/api/kick) | 2 | Kick clip transcript; Kick clip |
| [Snapchat](/docs/api/snapchat) | 3 | Snapchat public profile; Snapchat Spotlight video; Snapchat Spotlight comments |
| [Linktree](/docs/api/linktree) | 1 | Linktree page |
| [Komi](/docs/api/komi) | 1 | Komi page |
| [Pillar](/docs/api/pillar) | 1 | Pillar page |
| [Lnk.Bio](/docs/api/linkbio) | 1 | Lnk.Bio page |
| [Linkme](/docs/api/linkme) | 1 | Linkme page |
| [Creator contact details](/docs/api/creators) | 2 | Find a creator's other social profiles; Find a creator's public emails |
| [X (Twitter)](/docs/api/twitter) | 7 | X post search; X profile; X profile posts |
| [Facebook](/docs/api/facebook) | 25 | Facebook Ad Library search; Facebook Ad Library search (POST body); Facebook Ad Library ads by page |
| [Google](/docs/api/google) | 3 | Google Ads Transparency advertiser search; Google Ads Transparency ads by advertiser; Google Ads Transparency ad details |
| [LinkedIn](/docs/api/linkedin) | 7 | LinkedIn Ad Library search; LinkedIn Ad Library ad details; LinkedIn public person profile |
| [Amazon](/docs/api/amazon) | 1 | Amazon storefront products |
| [Spotify](/docs/api/spotify) | 7 | Spotify artist; Spotify album; Spotify track |
| [Apple Music](/docs/api/apple-music) | 4 | Apple Music artist; Apple Music album; Apple Music track |
| [SoundCloud](/docs/api/soundcloud) | 3 | SoundCloud artist; SoundCloud artist tracks; SoundCloud track |
| [GitHub](/docs/api/github) | 10 | GitHub user; GitHub user repositories; GitHub repository |
| [Kwai](/docs/api/kwai) | 3 | Kwai profile; Kwai profile posts; Kwai post |
| [Rumble](/docs/api/rumble) | 5 | Rumble video details; Rumble channel videos; Rumble search |
| [Telegram](/docs/api/telegram) | 3 | Telegram public channel; Telegram public channel posts; Telegram public post |
| [Cosmos](/docs/api/cosmos) | 7 | Cosmos profile; Cosmos profile posts; Cosmos profile collections |
| [Transcript from any URL](/docs/api/transcript) | 1 | Transcript from any video URL |
| [Account](/docs/api/account) | 4 | Credit balance; Request history; Daily usage |
| [Jobs](/docs/api/jobs) | 1 | Job result |
| [Batch](/docs/api/batch) | 1 | Batch requests |
| [Monitors](/docs/api/monitors) | 7 | Create a monitor; List monitors; Delete a monitor |

- [Data models](/docs/api/models): every field of every object the API returns.
- [OpenAPI document](https://api.socialscrape.io/openapi.json): the same reference as a machine-readable file, generated from the same source.
- [Responses](/docs/responses): the envelope around every answer.
- [Errors](/docs/errors): every error code, with its HTTP status and whether to retry.


---

# Data models

URL: https://socialscrape.io/docs/api/models

Every endpoint returns one of these models in `data`. The same field names mean the same thing on every platform. A field the platform does not provide is `null`, never invented; platform details with no field of their own are in `extra`. Pass `trim=true` to drop `null` fields and `extra`, or `raw=true` to also get the platform's original object next to `data`.

## Lists

Every list endpoint returns a `list` object. See [Pagination](/docs/pagination).

| Field | Type | Notes |
|---|---|---|
| `object` | `"list"` |  |
| `items` | array | The page of results; the type depends on the endpoint. |
| `cursor` | string or null | Pass it back unchanged for the next page. `null` on the last page. |
| `has_more` | boolean | Whether another page exists. |
| `parent` | object or null | The thing the list belongs to (a profile for its posts), where the platform returns it. |

## Activity

One public activity event (GitHub events).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"activity"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `type` | string | yes | platform's event type, snake_case: "push", "pull_request", "star" |
| `actor` | [Author](#author) or null |  |  |
| `repo` | string or null |  |  |
| `created_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## Ad

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"ad"` |  |  |
| `platform` | [Platform](#platform) | yes | the ad library's platform |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `advertiser` | [Advertiser](#advertiser) or null |  |  |
| `status` | `"active"` or `"inactive"` or `"unknown"` |  |  |
| `started_at` | string (ISO 8601 date-time) or null |  |  |
| `ended_at` | string (ISO 8601 date-time) or null |  |  |
| `title` | string or null |  |  |
| `body` | string or null |  |  |
| `cta_text` | string or null |  |  |
| `landing_url` | string or null |  |  |
| `format` | string or null |  | "image" \| "video" \| "carousel" \| "text" \| platform-specific |
| `media` | [Media](#media) |  |  |
| `regions` | string[] or null |  |  |
| `publisher_platforms` | string[] or null |  | where it ran: facebook, instagram, ... |
| `impressions` | [Range](#range) or null |  |  |
| `spend` | [Range](#range) or null |  |  |
| `extra` | object or null |  |  |

## Advertiser

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"advertiser"` |  |  |
| `platform` | [Platform](#platform) | yes | the ad library's platform |
| `id` | string or null |  |  |
| `name` | string or null |  |  |
| `url` | string or null |  |  |
| `page_id` | string or null |  |  |
| `country` | string or null |  |  |
| `verified` | boolean or null |  |  |
| `ad_count` | integer or null |  |  |
| `extra` | object or null |  |  |

## Album

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"album"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `title` | string or null |  |  |
| `artists` | string[] or null |  |  |
| `released_at` | string (ISO 8601 date) or null |  |  |
| `track_count` | integer or null |  |  |
| `cover_url` | string or null |  |  |
| `label` | string or null |  |  |
| `tracks` | [Song](#song)[] or null |  |  |
| `extra` | object or null |  |  |

## Author

Compact reference to a profile, embedded in posts, comments, ads.

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string or null |  |  |
| `handle` | string or null |  |  |
| `name` | string or null |  |  |
| `url` | string or null |  |  |
| `avatar_url` | string or null |  |  |
| `verified` | boolean or null |  |  |

## BatchItem

One envelope per batch request, in order. `response` is a full envelope.

| Field | Type | Required | Notes |
|---|---|---|---|
| `path` | string | yes |  |
| `status` | integer | yes |  |
| `response` | object | yes |  |

## BatchResult

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"batch"` |  |  |
| `results` | [BatchItem](#batchitem)[] | yes |  |

## Collection

An ordered set of items someone curates: playlists, boards, podcasts, highlights.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"collection"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `kind` | `"playlist"` or `"board"` or `"podcast"` or `"highlight"` or `"topic"` or `"collection"` or `"unknown"` |  |  |
| `title` | string or null |  |  |
| `description` | string or null |  |  |
| `owner` | [Author](#author) or null |  |  |
| `item_count` | integer or null |  |  |
| `cover_url` | string or null |  |  |
| `updated_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## Comment

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"comment"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `post_id` | string or null |  |  |
| `parent_id` | string or null |  | set on replies |
| `author` | [Author](#author) or null |  |  |
| `text` | string or null |  |  |
| `published_at` | string (ISO 8601 date-time) or null |  |  |
| `stats` | [CommentStats](#commentstats) |  |  |
| `is_pinned` | boolean or null |  |  |
| `is_by_creator` | boolean or null |  |  |
| `extra` | object or null |  |  |

## CommentStats

| Field | Type | Required | Notes |
|---|---|---|---|
| `likes` | integer or null |  |  |
| `replies` | integer or null |  |  |
| `dislikes` | integer or null |  |  |

## Community

A place people post into: subreddits, Facebook groups, X communities, Telegram channels.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"community"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string or null |  |  |
| `url` | string or null |  |  |
| `kind` | `"subreddit"` or `"group"` or `"community"` or `"channel"` or `"unknown"` |  |  |
| `name` | string or null |  | the slug, "python" for r/python |
| `title` | string or null |  |  |
| `description` | string or null |  |  |
| `avatar_url` | string or null |  |  |
| `banner_url` | string or null |  |  |
| `member_count` | integer or null |  |  |
| `online_count` | integer or null |  |  |
| `is_nsfw` | boolean or null |  |  |
| `is_private` | boolean or null |  |  |
| `verified` | boolean or null |  | the platform's verified badge (Telegram channels) |
| `created_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## ContributionDay

| Field | Type | Required | Notes |
|---|---|---|---|
| `date` | string (ISO 8601 date) | yes |  |
| `count` | integer | yes |  |

## Contributions

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"contributions"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `handle` | string or null |  |  |
| `total` | integer or null |  |  |
| `days` | [ContributionDay](#contributionday)[] or null |  |  |
| `extra` | object or null |  |  |

## CreatorEmails

Publicly listed emails for a creator, each with where it was found.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"creator_emails"` |  |  |
| `platform` | [Platform](#platform) | yes | the platform of the profile that was asked about |
| `handle` | string or null |  |  |
| `profile_url` | string or null |  |  |
| `emails` | [FoundEmail](#foundemail)[] | yes |  |
| `extra` | object or null |  |  |

## CreditBalance

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"credit_balance"` |  |  |
| `credits_remaining` | integer | yes |  |
| `team_id` | string | yes |  |

## Embed

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"embed"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `url` | string or null |  |  |
| `html` | string | yes |  |
| `extra` | object or null |  |  |

## Event

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"event"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `title` | string or null |  |  |
| `description` | string or null |  |  |
| `starts_at` | string (ISO 8601 date-time) or null |  |  |
| `ends_at` | string (ISO 8601 date-time) or null |  |  |
| `place` | [Place](#place) or null |  |  |
| `is_online` | boolean or null |  |  |
| `host` | [Author](#author) or null |  |  |
| `going_count` | integer or null |  |  |
| `interested_count` | integer or null |  |  |
| `cover_url` | string or null |  |  |
| `extra` | object or null |  |  |

## FoundEmail

| Field | Type | Required | Notes |
|---|---|---|---|
| `email` | string | yes |  |
| `source_url` | string or null |  | where it was published |
| `kind` | string or null |  | "business" \| "management" \| "personal" \| ... |

## JobAccepted

Answer for a job that is still running. Poll `poll_url` (free).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"job"` |  |  |
| `job_id` | string | yes |  |
| `status` | `"pending"` or `"running"` | yes |  |
| `poll_url` | string | yes |  |

## Link

| Field | Type | Required | Notes |
|---|---|---|---|
| `title` | string or null |  |  |
| `url` | string | yes |  |

## LinkPage

A link-in-bio page (Linktree, Komi, Pillar, Linkbio, Linkme).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"link_page"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `handle` | string or null |  |  |
| `url` | string or null |  |  |
| `name` | string or null |  |  |
| `bio` | string or null |  |  |
| `avatar_url` | string or null |  |  |
| `links` | [Link](#link)[] or null |  |  |
| `socials` | [Link](#link)[] or null |  | title = platform name |
| `extra` | object or null |  |  |

## LiveStream

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"live_stream"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `is_live` | boolean | yes |  |
| `id` | string or null |  | room / stream id |
| `url` | string or null |  |  |
| `author` | [Author](#author) or null |  |  |
| `title` | string or null |  |  |
| `viewer_count` | integer or null |  |  |
| `like_count` | integer or null |  |  |
| `started_at` | string (ISO 8601 date-time) or null |  |  |
| `cover_url` | string or null |  |  |
| `extra` | object or null |  |  |

## Location

A named place with coordinates (Facebook Marketplace city search).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"location"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string or null |  |  |
| `name` | string | yes |  |
| `region` | string or null |  | state / province |
| `country` | string or null |  | ISO 3166-1 alpha-2 when known |
| `latitude` | number or null |  |  |
| `longitude` | number or null |  |  |
| `extra` | object or null |  |  |

## Media

| Field | Type | Required | Notes |
|---|---|---|---|
| `thumbnail_url` | string or null |  |  |
| `video_url` | string or null |  |  |
| `audio_url` | string or null |  |  |
| `image_urls` | string[] or null |  |  |
| `width` | integer or null |  |  |
| `height` | integer or null |  |  |

## Monitor

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"monitor"` |  |  |
| `id` | string | yes |  |
| `endpoint` | string | yes | endpoint path it watches, "/v1/tiktok/profile/videos" |
| `params` | object | yes |  |
| `interval_minutes` | integer | yes |  |
| `webhook_url` | string | yes |  |
| `active` | boolean | yes | false: deleted, or paused after repeated failures (last_error says why) |
| `created_at` | string (ISO 8601 date-time) | yes |  |
| `webhook_secret` | string or null |  |  |
| `last_run_at` | string (ISO 8601 date-time) or null |  |  |
| `next_run_at` | string (ISO 8601 date-time) or null |  |  |
| `last_error` | string or null |  | error code of the last failed run, "insufficient_credits", ... |

## MonitorEvent

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"monitor_event"` |  |  |
| `id` | string | yes |  |
| `monitor_id` | string | yes |  |
| `type` | `"new_items"` | yes |  |
| `items` | object[] | yes | normalised objects, as the watched endpoint returns them |
| `created_at` | string (ISO 8601 date-time) | yes |  |

## Place

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string or null |  |  |
| `address` | string or null |  |  |
| `city` | string or null |  |  |
| `region` | string or null |  |  |
| `country` | string or null |  | ISO 3166-1 alpha-2 when known |
| `latitude` | number or null |  |  |
| `longitude` | number or null |  |  |

## Post

Videos, reels, tweets, pins, clips, stories, Reddit posts: all posts with a `type`.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"post"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `type` | `"video"` or `"short"` or `"reel"` or `"image"` or `"carousel"` or `"story"` or `"live"` or `"clip"` or `"text"` or `"link"` or `"tweet"` or `"pin"` or `"community_post"` or `"episode"` or `"unknown"` |  |  |
| `author` | [Author](#author) or null |  |  |
| `title` | string or null |  |  |
| `text` | string or null |  |  |
| `published_at` | string (ISO 8601 date-time) or null |  |  |
| `duration_seconds` | number or null |  |  |
| `language` | string or null |  |  |
| `hashtags` | string[] or null |  |  |
| `mentions` | string[] or null |  |  |
| `stats` | [Stats](#stats) |  |  |
| `media` | [Media](#media) |  |  |
| `song` | [SongRef](#songref) or null |  |  |
| `location` | [Place](#place) or null |  |  |
| `is_pinned` | boolean or null |  |  |
| `is_sponsored` | boolean or null |  |  |
| `extra` | object or null |  |  |

## Price

| Field | Type | Required | Notes |
|---|---|---|---|
| `amount` | number or null |  |  |
| `currency` | string or null |  | ISO 4217 |
| `original_amount` | number or null |  | before a discount |
| `display` | string or null |  | as the platform shows it, "$12.99" |

## Product

Shop products and marketplace listings.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"product"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `title` | string or null |  |  |
| `description` | string or null |  |  |
| `price` | [Price](#price) or null |  |  |
| `seller` | [Author](#author) or null |  |  |
| `rating` | number or null |  |  |
| `review_count` | integer or null |  |  |
| `sold_count` | integer or null |  |  |
| `image_urls` | string[] or null |  |  |
| `category` | string or null |  |  |
| `in_stock` | boolean or null |  |  |
| `location` | [Place](#place) or null |  |  |
| `published_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## Profile

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"profile"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string or null |  |  |
| `handle` | string or null |  |  |
| `name` | string or null |  |  |
| `headline` | string or null |  | a short tagline apart from the bio (LinkedIn's headline) |
| `url` | string or null |  |  |
| `kind` | `"person"` or `"creator"` or `"channel"` or `"page"` or `"company"` or `"artist"` or `"organization"` or `"shop"` or `"unknown"` |  |  |
| `bio` | string or null |  |  |
| `avatar_url` | string or null |  |  |
| `banner_url` | string or null |  |  |
| `verified` | boolean or null |  |  |
| `is_private` | boolean or null |  |  |
| `external_url` | string or null |  |  |
| `links` | [Link](#link)[] or null |  |  |
| `location` | string or null |  |  |
| `category` | string or null |  |  |
| `created_at` | string (ISO 8601 date-time) or null |  |  |
| `stats` | [ProfileStats](#profilestats) |  |  |
| `extra` | object or null |  |  |

## ProfileStats

| Field | Type | Required | Notes |
|---|---|---|---|
| `followers` | integer or null |  |  |
| `following` | integer or null |  |  |
| `posts` | integer or null |  |  |
| `likes` | integer or null |  |  |
| `views` | integer or null |  |  |

## PullRequest

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"pull_request"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `repo` | string or null |  | "owner/name" |
| `number` | integer or null |  |  |
| `title` | string or null |  |  |
| `state` | `"open"` or `"closed"` or `"merged"` or `"unknown"` |  |  |
| `author` | [Author](#author) or null |  |  |
| `created_at` | string (ISO 8601 date-time) or null |  |  |
| `closed_at` | string (ISO 8601 date-time) or null |  |  |
| `merged_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## Range

A bounded estimate as ad libraries publish them (impressions, spend).

| Field | Type | Required | Notes |
|---|---|---|---|
| `lower` | number or null |  |  |
| `upper` | number or null |  |  |
| `currency` | string or null |  |  |

## Repo

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"repo"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string or null |  |  |
| `full_name` | string | yes | "owner/name" |
| `name` | string or null |  |  |
| `url` | string or null |  |  |
| `owner` | [Author](#author) or null |  |  |
| `description` | string or null |  |  |
| `language` | string or null |  |  |
| `topics` | string[] or null |  |  |
| `license` | string or null |  |  |
| `stars` | integer or null |  |  |
| `forks` | integer or null |  |  |
| `watchers` | integer or null |  |  |
| `open_issues` | integer or null |  |  |
| `is_fork` | boolean or null |  |  |
| `is_archived` | boolean or null |  |  |
| `default_branch` | string or null |  |  |
| `created_at` | string (ISO 8601 date-time) or null |  |  |
| `updated_at` | string (ISO 8601 date-time) or null |  |  |
| `pushed_at` | string (ISO 8601 date-time) or null |  |  |
| `extra` | object or null |  |  |

## RequestLogEntry

One past API request of the team (account request history).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"request_log"` |  |  |
| `request_id` | string | yes |  |
| `endpoint` | string | yes | the path that was called, "/v1/tiktok/profile" |
| `endpoint_id` | string or null |  |  |
| `status` | integer | yes |  |
| `credits_charged` | integer | yes |  |
| `cached` | boolean or null |  |  |
| `created_at` | string (ISO 8601 date-time) | yes |  |

## Review

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"review"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `product_id` | string or null |  |  |
| `author` | [Author](#author) or null |  |  |
| `rating` | number or null |  |  |
| `text` | string or null |  |  |
| `published_at` | string (ISO 8601 date-time) or null |  |  |
| `image_urls` | string[] or null |  |  |
| `extra` | object or null |  |  |

## SearchResult

One organic web search result (Google search).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"search_result"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `position` | integer or null |  |  |
| `title` | string or null |  |  |
| `url` | string | yes |  |
| `displayed_url` | string or null |  |  |
| `snippet` | string or null |  |  |
| `kind` | string or null |  | "organic" \| "video" \| "news" \| ... |
| `extra` | object or null |  |  |

## Song

A sound or music track (TikTok sounds, Spotify/Apple/SoundCloud tracks).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"song"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `id` | string | yes |  |
| `url` | string or null |  |  |
| `title` | string or null |  |  |
| `artists` | string[] or null |  |  |
| `album` | string or null |  |  |
| `duration_seconds` | number or null |  |  |
| `cover_url` | string or null |  |  |
| `preview_url` | string or null |  |  |
| `released_at` | string (ISO 8601 date) or null |  |  |
| `isrc` | string or null |  |  |
| `explicit` | boolean or null |  |  |
| `is_original` | boolean or null |  | TikTok "original sound" |
| `stats` | [SongStats](#songstats) |  |  |
| `extra` | object or null |  |  |

## SongRef

The sound used by a post (TikTok, Reels, Shorts).

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string or null |  |  |
| `title` | string or null |  |  |
| `artist` | string or null |  |  |
| `url` | string or null |  |  |

## SongStats

| Field | Type | Required | Notes |
|---|---|---|---|
| `plays` | integer or null |  |  |
| `uses` | integer or null |  | videos made with the sound |
| `likes` | integer or null |  |  |

## Stats

Engagement on a post. Same five names on every platform.

| Field | Type | Required | Notes |
|---|---|---|---|
| `views` | integer or null |  |  |
| `likes` | integer or null |  |  |
| `comments` | integer or null |  |  |
| `shares` | integer or null |  |  |
| `saves` | integer or null |  |  |
| `dislikes` | integer or null |  | where the platform shows them (Rumble) |

## Suggestion

One search suggestion or typeahead entry (TikTok, YouTube, Instagram).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"suggestion"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `kind` | `"query"` or `"channel"` or `"user"` or `"hashtag"` or `"place"` or `"product"` or `"unknown"` |  |  |
| `text` | string | yes |  |
| `id` | string or null |  | channel / user / hashtag / place id when the platform gives one |
| `handle` | string or null |  |  |
| `url` | string or null |  |  |
| `image_url` | string or null |  |  |
| `verified` | boolean or null |  |  |
| `extra` | object or null |  |  |

## Transcript

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"transcript"` |  |  |
| `platform` | [Platform](#platform) | yes |  |
| `video_id` | string or null |  |  |
| `url` | string or null |  |  |
| `language` | string or null |  | BCP 47, "en" |
| `source` | `"captions"` or `"auto_captions"` or `"ai"` | yes |  |
| `duration_seconds` | number or null |  |  |
| `text` | string | yes |  |
| `segments` | [TranscriptSegment](#transcriptsegment)[] or null |  |  |
| `available_languages` | string[] or null |  |  |
| `extra` | object or null |  |  |

## TranscriptSegment

| Field | Type | Required | Notes |
|---|---|---|---|
| `start` | number | yes | seconds |
| `end` | number or null |  |  |
| `text` | string | yes |  |

## UsageStat

Aggregated usage: one day (`date` set) or one endpoint (`endpoint` set).

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"usage_stat"` |  |  |
| `date` | string (ISO 8601 date) or null |  |  |
| `endpoint` | string or null |  |  |
| `requests` | integer | yes |  |
| `credits_charged` | integer | yes |  |

## WebhookDelivery

One delivery attempt of a monitor event.

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"webhook_delivery"` |  |  |
| `event_id` | string | yes |  |
| `monitor_id` | string | yes |  |
| `attempt` | integer | yes |  |
| `status_code` | integer or null |  |  |
| `ok` | boolean | yes |  |
| `dead_letter` | boolean | yes | the last attempt of a chain that gave up; redeliver to try again |
| `error` | string or null |  |  |
| `created_at` | string (ISO 8601 date-time) | yes |  |

## WebhookRedelivery

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"webhook_redelivery"` |  |  |
| `event_id` | string | yes |  |
| `queued` | boolean | yes |  |
| `previous_state` | `"pending"` or `"retrying"` or `"dead"` | yes |  |

## WebhookTest

What the receiver answered to a signed test event ("type": "test").

| Field | Type | Required | Notes |
|---|---|---|---|
| `object` | `"webhook_test"` |  |  |
| `monitor_id` | string | yes |  |
| `delivered` | boolean | yes |  |
| `status_code` | integer or null |  |  |
| `error` | string or null |  |  |

## Platform

Allowed values: `youtube`, `tiktok`, `instagram`, `reddit`, `bluesky`, `threads`, `truthsocial`, `pinterest`, `twitch`, `kick`, `snapchat`, `linktree`, `komi`, `pillar`, `linkbio`, `linkme`, `twitter`, `facebook`, `linkedin`, `amazon`, `spotify`, `apple_music`, `soundcloud`, `github`, `kwai`, `rumble`, `telegram`, `google`, `cosmos`, `web`.


---

# Endpoint reference


## YouTube

### YouTube channel details

URL: https://socialscrape.io/docs/api/youtube/channel
Request: GET /v1/youtube/channel
Cost: 1 credit. Status: beta.

Name, avatar, subscribers, video and view counts, join date, country and linked links. Pass a `handle`, an `id` (channelId) or a channel `url`.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA"
```

### YouTube channel videos

URL: https://socialscrape.io/docs/api/youtube/channel-videos
Request: GET /v1/youtube/channel/videos
Cost: 1 credit. Status: beta.

A channel's uploads, newest first or most popular. Page with `cursor` (the continuationToken).

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- sort (string; optional; one of latest, popular; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- include_extras (boolean; optional; also includeExtras): Also fetch likes, comment count and description per video (slower, more errors). The video endpoint returns everything.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=MrBeast" \
  --data-urlencode "sort=popular"
```

### Search inside a YouTube channel

URL: https://socialscrape.io/docs/api/youtube/channel-search
Request: GET /v1/youtube/channel/search
Cost: 1 credit. Status: beta.

YouTube's own channel search: videos, Shorts, lives and playlists of one channel that match `query`. Keep the same channel and query while paging.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- query (string; required; also keyword, q): Keywords to search for inside the channel.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA" \
  --data-urlencode "query=artemis"
```

### YouTube channel playlists

URL: https://socialscrape.io/docs/api/youtube/channel-playlists
Request: GET /v1/youtube/channel/playlists
Cost: 1 credit. Status: beta.

Playlists from a channel's Playlists tab: id, title, thumbnail, video count and URL.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/playlists" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA"
```

### YouTube channel Shorts

URL: https://socialscrape.io/docs/api/youtube/channel-shorts
Request: GET /v1/youtube/channel/shorts
Cost: 1 credit. Status: beta.

A channel's Shorts, newest first or most popular: id, title and view count. YouTube's Shorts tab shows no length or date; `include_extras` adds them with likes and the description.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- sort (string; optional; one of latest, popular; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- include_extras (boolean; optional; also includeExtras): Also fetch length, publish date, likes and description per Short (slower, more errors).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/shorts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA"
```

### YouTube channel live streams

URL: https://socialscrape.io/docs/api/youtube/channel-lives
Request: GET /v1/youtube/channel/lives
Cost: 1 credit. Status: beta.

Live and past streams from a channel's Live tab. For a stream that is on air now, `stats.views` is the number watching, as YouTube's tab prints it.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/lives" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA"
```

### YouTube channel community posts

URL: https://socialscrape.io/docs/api/youtube/channel-community-posts
Request: GET /v1/youtube/channel/community-posts
Cost: 1 credit. Status: beta.

Posts from a channel's Posts tab: text, images, an attached video, likes and publish time.

Parameters:
- handle (string; optional; also username): Channel handle, with or without @.
- id (string; optional; also channelId, channel_id): Channel id (UC...).
- url (url; optional): Any channel URL (/@handle, /channel/UC..., /c/name).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/channel/community-posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA" \
  --data-urlencode "cursor=4qmFsgKBARIYVUNMQV9EaVIxRmZLTnZqdVVwQkhteWxRGkxFZ1Z3YjNOMGM2b0RLQW9rVVRKb1ExSkdVWGRVYTJ4UFlXMW9UMVZxUWxkVlZrVjNUVVJHVkdKVk5VUlNWVVpDS0FyeUJnUUtBa29BmgIWYmFja3N0YWdlLWl0ZW0tc2VjdGlvbg%3D%3D"
```

### YouTube video or Short details

URL: https://socialscrape.io/docs/api/youtube/video
Request: GET /v1/youtube/video
Cost: 1 credit. Status: beta.

Title, description, stats, duration, channel, thumbnails, chapters, caption tracks and whether YouTube marks it as paid promotion (`is_sponsored`, null when YouTube's player could not be read for this request). Views, likes and the publish time are exact; the comment and subscriber counts are the abbreviated figures YouTube shows logged out, with the display text in `extra`. Works for Shorts and lives.

Parameters:
- url (url; optional): Video or Short URL (watch, youtu.be, shorts, live, embed).
- id (string; optional; also videoId, video_id): 11-character video id.
- language (string; optional; also lang): Preferred response language, 2 letters (en, es, fr). Not guaranteed: YouTube localises on its own.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/video" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=QP5Fs3AYuWE"
```

### YouTube video transcript

URL: https://socialscrape.io/docs/api/youtube/video-transcript
Request: GET /v1/youtube/video/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

The video's own captions: the language you ask for (or the original audio's), typed by the uploader or recognised by YouTube (`source`), with the languages on offer. A video without captions answers transcript_unavailable and costs nothing; AI transcription of YouTube audio is not available yet.

Parameters:
- url (url; optional): Video or Short URL (watch, youtu.be, shorts, live, embed).
- id (string; optional; also videoId, video_id): 11-character video id.
- language (string; optional; also lang): Language code ("en", "es", "en-US"). Overrides the default track unless `original_audio` is set.
- original_audio (boolean; optional): Only return captions in the video's original spoken language. Takes precedence over `language`.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/video/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=dQw4w9WgXcQ" \
  --data-urlencode "language=de"
```

### YouTube video sponsors

URL: https://socialscrape.io/docs/api/youtube/video-sponsors
Request: GET /v1/youtube/video/sponsors
Cost: 1 credit. Status: beta.

Experimental. Whether the video discloses paid promotion, and the suspected sponsors with confidence and evidence in `extra`, inferred from the public description, its links, promo codes and the transcript. An inference, not a statement from YouTube; `parent` is the video.

Parameters:
- url (url; optional): Video or Short URL (watch, youtu.be, shorts, live, embed).
- id (string; optional; also videoId, video_id): 11-character video id.
- language (string; optional; also lang): 2-letter language used for the transcript lookup.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/video/sponsors" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=JsBZOcqZerk"
```

### YouTube search

URL: https://socialscrape.io/docs/api/youtube/search
Request: GET /v1/youtube/search
Cost: 1 credit. Status: beta.

Videos, channels, playlists, Shorts and live streams for a query. Shorts and live results are Posts of type `short` and `live`. For stricter title matching use YouTube's `intitle:` operator.

Parameters:
- query (string; required; also keyword, q): Search terms.
- type (string; optional; one of video, channel, playlist, short, live; also filter): Kind of result.
- upload_date (string; optional; one of hour, today, week, month, year; also uploadDate): Upload date filter.
- duration (string; optional; one of short, medium, long): Video length (videos only, not Shorts).
- sort (string; optional; one of relevance, latest, popular, rating; also sort_by, sortBy, order): Order of results. YouTube now answers `latest` and `rating` in relevance order, so they are refused with invalid_params; use `relevance` or `popular` (view count) and narrow with `upload_date`.
- include_extras (boolean; optional; also includeExtras): Also fetch likes, comment count and description per video (slightly slower).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=lofi hip hop" \
  --data-urlencode "type=playlist"
```

### YouTube search suggestions

URL: https://socialscrape.io/docs/api/youtube/search-typeahead
Request: GET /v1/youtube/search/typeahead
Cost: 1 credit. Status: beta.

The live suggestions YouTube shows while a user types. Channel suggestions carry the channel id, handle, name and thumbnail.

Parameters:
- query (string; required; also keyword, q): Partial or complete search text.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/search/typeahead" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=mr beast"
```

### YouTube videos by hashtag

URL: https://socialscrape.io/docs/api/youtube/search-hashtag
Request: GET /v1/youtube/search/hashtag
Cost: 1 credit. Status: beta.

Videos (or Shorts) on a hashtag's page. The `all` tab holds about 30 videos and usually no next page; the `short` tab pages with `cursor`.

Parameters:
- hashtag (string; required): Hashtag, with or without #.
- type (string; optional; one of all, short): Kind of result.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/search/hashtag" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "hashtag=minecraft"
```

### YouTube video comments

URL: https://socialscrape.io/docs/api/youtube/video-comments
Request: GET /v1/youtube/video/comments
Cost: 1 credit. Status: beta.

Comments (about 1,000 top or 7,000 newest at most). Page with `cursor`.

Parameters:
- url (url; optional): Video or Short URL (watch, youtu.be, shorts, live, embed).
- id (string; optional; also videoId, video_id): 11-character video id.
- sort (string; optional; one of top, latest; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/video/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=dQw4w9WgXcQ" \
  --data-urlencode "sort=latest"
```

### YouTube comment replies

URL: https://socialscrape.io/docs/api/youtube/video-comment-replies
Request: GET /v1/youtube/video/comment/replies
Cost: 1 credit. Status: beta.

Replies to one comment. Pass the comment's replies cursor from the comments list as `cursor` The cursor alone is enough (ScrapeCreators' `continuationToken`); the handler rejects a call with no cursor.

Parameters:
- url (url; optional): Video or Short URL (watch, youtu.be, shorts, live, embed).
- id (string; optional; also videoId, video_id): 11-character video id.
- comment_id (string; optional; also commentId): Id of the parent comment.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/video/comment/replies" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=dQw4w9WgXcQ" \
  --data-urlencode "comment_id=UgwPwTibxdgqCHZxktd4AaABAg" \
  --data-urlencode "cursor=Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIaVWd3UHdUaWJ4ZGdxQ0haeGt0ZDRBYUFCQWciAggAKhhVQ3VBWEZrZ3N3MUw3eGFDZm5kNUpKT3cyC2RRdzR3OVdnWGNRQAFICoIBAggBQi9jb21tZW50LXJlcGxpZXMtaXRlbS1VZ3dQd1RpYnhkZ3FDSFp4a3RkNEFhQUJBZw%3D%3D"
```

### Trending YouTube Shorts

URL: https://socialscrape.io/docs/api/youtube/shorts-trending
Request: GET /v1/youtube/shorts/trending
Cost: 1 credit. Status: beta.

YouTube has no logged-out trending page; this is the anonymous Shorts feed (about ten Shorts a page, different on each call, not a ranked chart), each with its title, channel, counts and date.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/shorts/trending" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "region=US"
```

### YouTube playlist videos

URL: https://socialscrape.io/docs/api/youtube/playlist
Request: GET /v1/youtube/playlist
Cost: 1 credit. Status: beta.

The playlist's videos; `parent` is the playlist itself.

Parameters:
- url (url; optional): Playlist URL (list=...).
- id (string; optional; also playlist_id, playlistId): Playlist id (PL..., UU..., OL...).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/playlist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=PL2aBZuCeDwlTxZeGRlKrWpLiX_W7jpt6p"
```

### YouTube community post

URL: https://socialscrape.io/docs/api/youtube/community-post
Request: GET /v1/youtube/community-post
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Community post URL (/post/Ug... or /channel/.../community?lb=...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/youtube/community-post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.youtube.com/post/Ugkx-7xgRw-Uc9lRS3_2RvS2zASPTZOFtIlw"
```


## TikTok

### TikTok profile

URL: https://socialscrape.io/docs/api/tiktok/profile
Request: GET /v1/tiktok/profile
Cost: 1 credit. Status: beta.

Public profile of a TikTok account: name, bio, bio link, verification and exact counts. Pass `handle` or the numeric user id as `id` (a secUid cannot be looked up logged out).

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id, secUid, sec_uid): TikTok user id (numeric) or secUid.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=khaby.lame"
```

### TikTok profile videos

URL: https://socialscrape.io/docs/api/tiktok/profile-videos
Request: GET /v1/tiktok/profile/videos
Cost: 1 credit. Status: beta.

The newest videos of a public account, from TikTok's embed page for it (no login). One page of about 10 (pinned videos first, then newest first), and no cursor: `has_more` is false because more cannot be fetched logged out, not because the account has no more. Each video has its id, caption, hashtags, cover, a signed play URL, size and play count (TikTok rounds it to two significant digits; `extra.views_rounded`), and a date taken from the video id (`extra.published_at_from_id`). Likes, comments, shares and duration are not on that page and stay null; `is_pinned` is true for a pinned video that can be told from the order (it never over-reports). `parent` is the account. `sort=popular` is refused, and a numeric `id` cannot be looked up: pass `handle`. A private account answers `private`.

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id, secUid, sec_uid): TikTok user id (numeric) or secUid.
- sort (string; optional; one of latest, popular; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- include_pinned (boolean; optional): Set false to drop the pinned videos that can be told from the page order.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/profile/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=khaby.lame"
```

### TikTok collection videos

URL: https://socialscrape.io/docs/api/tiktok/collection-videos
Request: GET /v1/tiktok/collection/videos
Cost: 1 credit. Status: beta.

Videos saved in a public TikTok collection (also called a playlist).

Parameters:
- url (url; required): Public collection URL (tiktok.com/@user/collection/<name>-<id>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/collection/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@kibblemaster808/collection/Want-to-go-7665668414573546258"
```

### TikTok video details

URL: https://socialscrape.io/docs/api/tiktok/video
Request: GET /v1/tiktok/video
Cost: 1 credit. Status: beta.

Metadata and engagement stats of one video or photo slideshow. `get_transcript=true` adds the native captions in `extra.transcript`; for AI transcription use `/v1/tiktok/video/transcript`.

Parameters:
- url (url; optional): Video URL (www.tiktok.com/@user/video/..., vm.tiktok.com/..., vt.tiktok.com/...).
- id (string; optional; also aweme_id, video_id): Numeric video id.
- get_transcript (boolean; optional): Include the video's native captions when it has them.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/video" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@khaby.lame/video/7137423965982592302"
```

### TikTok video transcript

URL: https://socialscrape.io/docs/api/tiktok/video-transcript
Request: GET /v1/tiktok/video/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

TikTok's own captions when the video has them (the English track first, else the first one); AI transcription of the audio when it does not. `language` steers the AI transcription only.

Parameters:
- url (url; optional): Video URL (www.tiktok.com/@user/video/..., vm.tiktok.com/..., vt.tiktok.com/...).
- id (string; optional; also aweme_id, video_id): Numeric video id.
- language (string; optional; also lang): Preferred caption language (2-letter code: en, es, fr, de, it, ja, ko, zh).
- ai_fallback (boolean; optional; also use_ai_as_fallback): Transcribe the audio with AI when the video has no captions. Set false to get no transcript instead, and no AI charge.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/video/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@nasa/video/7665075736742530317"
```

### TikTok video comments

URL: https://socialscrape.io/docs/api/tiktok/video-comments
Request: GET /v1/tiktok/video/comments
Cost: 1 credit. Status: beta.

Comments on a video, with the commenter and like and reply counts.

Parameters:
- url (url; optional): Video URL (www.tiktok.com/@user/video/..., vm.tiktok.com/..., vt.tiktok.com/...).
- id (string; optional; also aweme_id, video_id): Numeric video id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/video/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@khaby.lame/video/7137423965982592302"
```

### TikTok comment replies

URL: https://socialscrape.io/docs/api/tiktok/video-comment-replies
Request: GET /v1/tiktok/video/comment/replies
Cost: 1 credit. Status: beta.

Parameters:
- url (url; optional): Video URL (www.tiktok.com/@user/video/..., vm.tiktok.com/..., vt.tiktok.com/...).
- id (string; optional; also aweme_id, video_id): Numeric video id.
- comment_id (string; required; also commentId, cid): TikTok comment id (the `cid` from the comments list).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/video/comment/replies" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/@khaby.lame/video/7137423965982592302" \
  --data-urlencode "comment_id=7137510823549272878"
```

### TikTok user search

URL: https://socialscrape.io/docs/api/tiktok/search-users
Request: GET /v1/tiktok/search/users
Cost: 1 credit. Status: beta.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/search/users" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nasa"
```

### TikTok search suggestions

URL: https://socialscrape.io/docs/api/tiktok/search-suggestions
Request: GET /v1/tiktok/search/suggestions
Cost: 1 credit. Status: beta.

The autocomplete suggestions TikTok shows while someone types in search.

Parameters:
- query (string; required; also keyword, q): Partial or complete search text.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/search/suggestions" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=dogs"
```

### TikTok video search

URL: https://socialscrape.io/docs/api/tiktok/search-keyword
Request: GET /v1/tiktok/search/keyword
Cost: 1 credit. Status: beta.

Video search across TikTok. TikTok ignores sort and date filters logged out: `sort` other than `relevance` is refused, and `date_posted` drops videos older than the window from each page (pages can be short or empty; follow `has_more`). `region` is TikTok's region hint, not a proxy country.

Parameters:
- query (string; required; also keyword, q): Search terms.
- sort (string; optional; one of relevance, likes, latest; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- date_posted (string; optional; one of any, day, week, month, three_months, six_months; also datePosted): Posted within.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/search/keyword" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nasa" \
  --data-urlencode "date_posted=week"
```

### TikTok videos by hashtag

URL: https://socialscrape.io/docs/api/tiktok/search-hashtag
Request: GET /v1/tiktok/search/hashtag
Cost: 1 credit. Status: beta.

Videos under a hashtag, with the hashtag (its video and view counts) as `parent`. TikTok may return duplicates.

Parameters:
- hashtag (string; required): Hashtag, with or without #.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/search/hashtag" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "hashtag=booktok"
```

### TikTok top search

URL: https://socialscrape.io/docs/api/tiktok/search-top
Request: GET /v1/tiktok/search/top
Cost: 1 credit. Status: beta.

TikTok's 'Top' tab: videos, photo carousels and a card of matching accounts (keyword search returns videos only). Same filter limits as keyword search: relevance order only; `publish_time` drops older items from each page.

Parameters:
- query (string; required; also keyword, q): Search terms.
- publish_time (string; optional; one of any, day, week, month, three_months, six_months): Posted within.
- sort (string; optional; one of relevance, likes, latest; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/search/top" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nasa"
```

### Popular TikTok videos

URL: https://socialscrape.io/docs/api/tiktok/videos-popular
Request: GET /v1/tiktok/videos/popular
Cost: 1 credit. Status: beta.

Videos from TikTok's Explore feed, the nearest public list to 'popular' (the Creative Center ranking behind ScrapeCreators' endpoint needs a login). `period` and `sort` are accepted for compatibility and not applied; `category` picks an Explore category.

Parameters:
- period (string; optional; one of 7, 30): Accepted for compatibility; the Explore feed has no time window.
- sort (string; optional; one of views, likes, comments, shares; also sort_by, sortBy, order): Accepted for compatibility; not applied.
- category (string; optional): TikTok's numeric Explore category id (default 1).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/videos/popular" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "region=US"
```

### TikTok song details

URL: https://socialscrape.io/docs/api/tiktok/song
Request: GET /v1/tiktok/song
Cost: 1 credit. Status: beta.

A sound by its clip id (the number at the end of a tiktok.com/music/... URL).

Parameters:
- id (string; optional; also clipId, music_id): Sound (music) id.
- url (url; optional): Sound URL (tiktok.com/music/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/song" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=7016547803243022337"
```

### TikTok videos using a song

URL: https://socialscrape.io/docs/api/tiktok/song-videos
Request: GET /v1/tiktok/song/videos
Cost: 1 credit. Status: beta.

Parameters:
- id (string; optional; also clipId, music_id): Sound (music) id.
- url (url; optional): Sound URL (tiktok.com/music/...).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/song/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=7016547803243022337"
```

### TikTok trending feed

URL: https://socialscrape.io/docs/api/tiktok/trending
Request: GET /v1/tiktok/trending
Cost: 1 credit. Status: beta.

The anonymous For You feed: a handful of videos per call, different on every call (the feed is not stable, so pages can repeat).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/trending" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "region=US"
```

### Is a TikTok user live

URL: https://socialscrape.io/docs/api/tiktok/profile-live
Request: GET /v1/tiktok/profile/live
Cost: 1 credit. Status: beta.

Whether the user is live now, with the room's details when they are.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/profile/live" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=khaby.lame"
```

### TikTok live room info

URL: https://socialscrape.io/docs/api/tiktok/live
Request: GET /v1/tiktok/live
Cost: 1 credit. Status: beta.

Room-level info for a live. Find the room id with `/v1/tiktok/profile/live`.

Parameters:
- url (url; optional): Live URL (tiktok.com/@user/live).
- id (string; optional; also room_id): Live room id.
- user_id (string; optional): Numeric TikTok user id of the live's owner (`id` from the profile); speeds the lookup.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/live" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=7702259688670235405"
```


## Instagram

### Instagram profile

URL: https://socialscrape.io/docs/api/instagram/profile
Request: GET /v1/instagram/profile
Cost: 1 credit. Status: beta.

Biography, links, follower and following counts and account flags. `stats.posts` is null here (Instagram's profile query leaves it out): use `profile/post-count`. Private accounts answer the profile with `is_private` true.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```

### Instagram profile by user id

URL: https://socialscrape.io/docs/api/instagram/basic-profile
Request: GET /v1/instagram/basic-profile
Cost: 1 credit. Status: beta.

A profile summary by numeric user id: username, name, biography, links, picture, verification, follower and following counts, account privacy. `stats.posts` is null (use `profile/post-count`). Instagram has no logged-out lookup by id, so the account is found through its newest public post: an id whose account has no public posts (private, empty or unknown) answers not_found.

Parameters:
- id (string; required; also userId, user_id): Numeric Instagram user id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/basic-profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=528817151"
```

### Instagram profile post count

URL: https://socialscrape.io/docs/api/instagram/profile-post-count
Request: GET /v1/instagram/profile/post-count
Cost: 1 credit. Status: beta.

The profile with `stats.posts` filled in, for when `profile` returns it null. Read from the profile's embed page, which carries the exact count even above 10,000 posts (`extra.is_estimated` false); only if that page is unavailable does it fall back to the profile page, which abbreviates.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.
- allow_estimated (boolean; optional): Return a scaled estimate when Instagram abbreviates the count (profiles over 10,000 posts). Without it such a profile answers an unbilled error.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile/post-count" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```

### Instagram profile posts

URL: https://socialscrape.io/docs/api/instagram/profile-posts
Request: GET /v1/instagram/profile/posts
Cost: 1 credit. Status: beta.

A paged feed of public posts: photos, videos, carousels and reels, 12 a page. Instagram's feed query carries no counts, so rows have captions, times and media URLs and every count in `stats` null; `require_play_counts=true` adds the likes, comments and (for videos) views of every post from its embed page, which is slower. Look a profile up by `handle`; a numeric `id` has no logged-out lookup.

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id, userId): Numeric Instagram user id.
- require_play_counts (boolean; optional): Add likes, comments and video views to every row (one extra page per post), and fail rather than return a video post whose play count is missing (a real 0 is fine).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```

### Instagram profile reels

URL: https://socialscrape.io/docs/api/instagram/profile-reels
Request: GET /v1/instagram/profile/reels
Cost: 1 credit. Status: beta.

A paged feed of the profile's public reels, 12 a page, with play, like and comment counts, caption, exact time, duration and video URL. `stats.views` is Instagram's play count (`extra.views_source` = plays). Look a profile up by `handle`.

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id, userId): Numeric Instagram user id.
- require_play_counts (boolean; optional): Fail rather than return a reel whose play count is missing.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile/reels" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```

### Instagram post or reel details

URL: https://socialscrape.io/docs/api/instagram/post
Request: GET /v1/instagram/post
Cost: 1 credit. Status: beta.

Caption, counts, media, owner, tagged users, co-authors, sound and carousel children of one post or reel. For videos `stats.views` is the view count of the post's embed page (`extra.views_source` = embed_views), which differs from the play count of the reels tab.

Parameters:
- url (url; optional): Post or reel URL (/p/..., /reel/..., /tv/...).
- id (string; optional; also shortcode, media_id): Shortcode or numeric media id.
- include_play_count (boolean; optional): Set false to skip the extra fetch for the video view count and answer faster.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.instagram.com/reel/DfF3eqGSKKc/"
```

### Instagram reel transcript

URL: https://socialscrape.io/docs/api/instagram/post-transcript
Request: GET /v1/instagram/post/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

AI transcription of a reel or video post (Instagram has no public captions). The post's video file is read from its public embed page and transcribed on the shared speech boxes at the transcript price (1 credit per started 5 minutes of audio). Photos and carousels without a video answer transcript_unavailable, which is free.

Parameters:
- url (url; optional): Post or reel URL (/p/..., /reel/..., /tv/...).
- id (string; optional; also shortcode, media_id): Shortcode or numeric media id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/post/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.instagram.com/reel/C8rKmYvsrck/"
```

### Instagram post comments

URL: https://socialscrape.io/docs/api/instagram/post-comments
Request: GET /v1/instagram/post/comments
Cost: 1 credit. Status: beta.

The first page of a post's comments (about 14, in Instagram's own order), with each comment's likes; reply counts are null (Instagram sends them empty to logged-out visitors). Instagram offers no logged-out way to the next page, so `has_more` is always false and the total is in the post's `stats.comments`. `include_replies` is accepted and ignored: replies need a login.

Parameters:
- url (url; optional): Post or reel URL (/p/..., /reel/..., /tv/...).
- id (string; optional; also shortcode, media_id): Shortcode or numeric media id.
- include_replies (boolean; optional): Accepted for compatibility; replies are not available logged out, so it changes nothing.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/post/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.instagram.com/reel/DfF3eqGSKKc/"
```

### Instagram popular topic

URL: https://socialscrape.io/docs/api/instagram/search-popular
Request: GET /v1/instagram/search/popular
Cost: 1 credit. Status: beta.

Explore a topic through Instagram's public Popular search: the reels it curates for a keyword, about 50 to 70 over 5 or 6 pages (health and finance terms are thin; some single words have none). Rows carry the caption, author, time and duration; Instagram sends no counts here, so every count in `stats` is null. No `parent`. Pass the cursor back with the same query.

Parameters:
- query (string; required; also keyword, q): The Popular topic to look up.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/search/popular" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=basketball"
```

### Instagram reel search

URL: https://socialscrape.io/docs/api/instagram/search-reels
Request: GET /v1/instagram/search/reels
Cost: 1 credit. Status: beta.

Reels for a keyword or phrase from Instagram's public Popular search (the same source as `search/popular`; it is not Google-indexed), about 50 to 70 over 5 or 6 pages. `date_posted` is accepted for compatibility and not applied: Popular search has no date filter.

Parameters:
- query (string; required; also keyword, q): Search terms.
- date_posted (string; optional; one of week, month, year): Accepted for compatibility; not applied (no date filter upstream).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/search/reels" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=sourdough"
```

### Instagram trending reels

URL: https://socialscrape.io/docs/api/instagram/reels-trending
Request: GET /v1/instagram/reels/trending
Cost: 1 credit. Status: beta.

Reels from Instagram's anonymous logged-out Reels feed, 8 a page, with like and comment counts (the feed carries no play counts), caption, author and video URL. The feed is whatever Instagram serves an anonymous visitor from the engine's region, so it changes from call to call.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/instagram/reels/trending" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Instagram story highlights

URL: https://socialscrape.io/docs/api/instagram/profile-highlights
Request: GET /v1/instagram/profile/highlights
Cost: 1 credit. Status: beta.

The profile's highlight albums: id, title, cover and owner. Look a profile up by `handle`; a numeric `id` has no logged-out lookup.

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id, userId): Numeric Instagram user id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile/highlights" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```

### Instagram highlight stories

URL: https://socialscrape.io/docs/api/instagram/highlight
Request: GET /v1/instagram/highlight
Cost: 1 credit. Status: beta.

The stories in one highlight; `parent` is the highlight.

Parameters:
- id (string; required; also highlight_id): Highlight id (from profile/highlights) or a /stories/highlights/ URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/highlight" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=18195781759377100"
```

### Instagram reels using a song

URL: https://socialscrape.io/docs/api/instagram/song-reels
Request: GET /v1/instagram/song/reels
Cost: 1 credit. Status: beta.

The reels that use one sound, from the data behind instagram.com/reels/audio/<id>/: 12 a page with play, like and comment counts, caption, author, time, duration and video URL; `parent` is the sound (a licensed track or a creator's original audio, with how many reels use it in `stats.uses`). Works for the id in the audio page's URL.

Parameters:
- id (string; required; also audio_id, audioId): Audio id from the audio page URL (instagram.com/reels/audio/<id>/).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/song/reels" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1392969992841787"
```

### Instagram profile embed HTML

URL: https://socialscrape.io/docs/api/instagram/profile-embed
Request: GET /v1/instagram/profile/embed
Cost: 1 credit. Status: beta.

The profile's embed document (what Instagram serves at /<handle>/embed/): HTML in `html`, with the follower and post counts it carries in `extra`.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/instagram/profile/embed" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=nasa"
```


## Bluesky

### Bluesky profile

URL: https://socialscrape.io/docs/api/bluesky/profile
Request: GET /v1/bluesky/profile
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; required; also username): Handle (alice.bsky.social) or DID (did:plc:...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/bluesky/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=bsky.app"
```

### Bluesky profile posts

URL: https://socialscrape.io/docs/api/bluesky/profile-posts
Request: GET /v1/bluesky/profile/posts
Cost: 1 credit. Status: beta.

A paged feed of the user's posts. Pass the DID (ScrapeCreators' `user_id`) for faster lookups.

Parameters:
- handle (string; required; also username, user_id): Handle (alice.bsky.social) or DID (did:plc:...).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/bluesky/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=bsky.app"
```

### Bluesky post

URL: https://socialscrape.io/docs/api/bluesky/post
Request: GET /v1/bluesky/post
Cost: 1 credit. Status: beta.

The post with its embed content and counts, and its threaded replies in `extra.replies`.

Parameters:
- url (url; required): Post URL (bsky.app/profile/<handle>/post/<rkey>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/bluesky/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g"
```


## Threads

### Threads profile

URL: https://socialscrape.io/docs/api/threads/profile
Request: GET /v1/threads/profile
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/threads/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=zuck"
```

### Threads profile posts

URL: https://socialscrape.io/docs/api/threads/profile-posts
Request: GET /v1/threads/profile/posts
Cost: 1 credit. Status: beta.

The most recent posts, newest first, about 15 per page. Threads shows logged-out visitors only the latest 20 to 30 posts of a profile, so paging runs out early.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/threads/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=zuck"
```

### Threads post

URL: https://socialscrape.io/docs/api/threads/post
Request: GET /v1/threads/post
Cost: 1 credit. Status: beta.

The post with its counts and media, and its top replies in `extra.replies`.

Parameters:
- url (url; required): Post URL (threads.net/@user/post/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/threads/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.threads.com/@zuck/post/DeZtp-TkQHh"
```

### Threads post search

URL: https://socialscrape.io/docs/api/threads/search
Request: GET /v1/threads/search
Cost: 1 credit. Status: beta.

Posts matching a keyword: one page of about 15 to 20 results, no paging. `start_date` and `end_date` filter the page by post date (Threads does not apply them itself).

Parameters:
- query (string; required; also keyword, q): Search terms.
- start_date (string; optional; also startDate): Only posts from this date (YYYY-MM-DD).
- end_date (string; optional; also endDate): Only posts up to this date (YYYY-MM-DD).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/threads/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=basketball"
```

### Threads user search

URL: https://socialscrape.io/docs/api/threads/search-users
Request: GET /v1/threads/search/users
Cost: 1 credit. Status: beta.

Accounts matching a query. Threads has no logged-out account search, so these are the authors of the search results whose handle or name matches, best match first, plus the account whose handle is the query itself.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/threads/search/users" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nasa"
```


## Truth Social

### Truth Social profile

URL: https://socialscrape.io/docs/api/truthsocial/profile
Request: GET /v1/truthsocial/profile
Cost: 1 credit. Status: beta.

Public profile of a Truth Social account. Accounts that do not exist answer not_found.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/truthsocial/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=realDonaldTrump"
```

### Truth Social profile posts

URL: https://socialscrape.io/docs/api/truthsocial/profile-posts
Request: GET /v1/truthsocial/profile/posts
Cost: 1 credit. Status: beta.

A paged list of the account's own posts (ReTruths are left out), newest first. A numeric `id` (the profile's id) saves a lookup call.

Parameters:
- handle (string; optional; also username): Username, with or without the leading @.
- id (string; optional; also user_id): Truth Social user id (the `id` from the profile).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/truthsocial/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=realDonaldTrump"
```

### Truth Social post

URL: https://socialscrape.io/docs/api/truthsocial/post
Request: GET /v1/truthsocial/post
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Post URL (truthsocial.com/@user/<id>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/truthsocial/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://truthsocial.com/@realDonaldTrump/117526232618166329"
```


## Pinterest

### Pinterest pin search

URL: https://socialscrape.io/docs/api/pinterest/search
Request: GET /v1/pinterest/search
Cost: 1 credit. Status: beta.

Pins matching a keyword, about 24 per page. Search pins carry opaque ids (e1_...), so their `url` is the pin page but the pin endpoint cannot look the id up again.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pinterest/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=living room ideas"
```

### Pinterest pin

URL: https://socialscrape.io/docs/api/pinterest/pin
Request: GET /v1/pinterest/pin
Cost: 1 credit. Status: beta.

One pin: title, description, outbound link, board, pinner, saves, reactions and image or video. Needs the numeric pin id in the URL; pin.it short links are followed.

Parameters:
- url (url; required): Pin URL (pinterest.com/pin/..., pin.it/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pinterest/pin" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.pinterest.com/pin/36662184461578355/"
```

### Pinterest user boards

URL: https://socialscrape.io/docs/api/pinterest/profile-boards
Request: GET /v1/pinterest/profile/boards
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pinterest/profile/boards" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=pinterest"
```

### Pinterest board pins

URL: https://socialscrape.io/docs/api/pinterest/board
Request: GET /v1/pinterest/board
Cost: 1 credit. Status: beta.

The board's pins, 25 per page; `parent` is the board. Logged out, Pinterest hands out a bookmark for the next page on some boards and none on others (a 183-pin board stops after its first 25), so follow `cursor` while `has_more` is true and expect large boards to come back partial.

Parameters:
- url (url; required): Board URL (pinterest.com/<user>/<board>/).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pinterest/board" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.pinterest.com/pinterest/holiday-decor-ideas/"
```

### Pinterest topic pins

URL: https://socialscrape.io/docs/api/pinterest/topic
Request: GET /v1/pinterest/topic
Cost: 1 credit. Status: beta.

Pins for an ideas topic. `parent` is the topic with its `search_count` and related `refinements` (first page only: they come from the ideas page).

Parameters:
- url (url; required): Topic URL (pinterest.com/ideas/<topic>/<id>/).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pinterest/topic" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.pinterest.com/ideas/how-to-stop-leash-pulling/894604313079/"
```


## Twitch

### Twitch channel

URL: https://socialscrape.io/docs/api/twitch/profile
Request: GET /v1/twitch/profile
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitch/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=shroud"
```

### Twitch user videos

URL: https://socialscrape.io/docs/api/twitch/user-videos
Request: GET /v1/twitch/user/videos
Cost: 1 credit. Status: beta.

A channel's videos (up to 100): id, title, views, game, duration and thumbnails.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.
- type (string; optional; one of highlight, archive, upload; also filter_by, filter): Kind of video.
- sort (string; optional; one of time, views; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- limit (integer; optional): How many videos to return, up to 100 (Twitch allows no paging past the first 100 without a browser session, so the response has no cursor).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitch/user/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=shroud" \
  --data-urlencode "type=highlight" \
  --data-urlencode "sort=views" \
  --data-urlencode "limit=10"
```

### Twitch stream schedule

URL: https://socialscrape.io/docs/api/twitch/user-schedule
Request: GET /v1/twitch/user/schedule
Cost: 1 credit. Status: beta.

A channel's scheduled streams: start and end time, title, categories and whether a stream is cancelled.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitch/user/schedule" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=emongg"
```

### Twitch clip transcript

URL: https://socialscrape.io/docs/api/twitch/clip-transcript
Request: GET /v1/twitch/clip/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Native captions when the clip has them; AI transcription of the clip's audio when it does not.

Parameters:
- url (url; required): Clip URL (clips.twitch.tv/... or twitch.tv/<user>/clip/...).
- ai_fallback (boolean; optional; also use_ai_as_fallback): Transcribe the audio with AI when the clip has no captions. Set false to get no transcript instead, and no AI charge.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitch/clip/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.twitch.tv/mish/clip/WrongMagnificentTomatoCorgiDerp-C720OEMqocSPbrqA"
```

### Twitch clip

URL: https://socialscrape.io/docs/api/twitch/clip
Request: GET /v1/twitch/clip
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Clip URL (clips.twitch.tv/... or twitch.tv/<user>/clip/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitch/clip" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.twitch.tv/mish/clip/WrongMagnificentTomatoCorgiDerp-C720OEMqocSPbrqA"
```


## Kick

### Kick clip transcript

URL: https://socialscrape.io/docs/api/kick/clip-transcript
Request: GET /v1/kick/clip/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Kick clips carry no caption track, so this is AI transcription of the clip's audio (flat 1 credit for clips of up to two minutes). With ai_fallback=false nothing is transcribed and nothing is charged.

Parameters:
- url (url; required): Clip URL (kick.com/<user>/clips/clip_...).
- ai_fallback (boolean; optional; also use_ai_as_fallback): Transcribe the audio with AI when the clip has no captions. Set false to get no transcript instead, and no AI charge.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/kick/clip/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://kick.com/xqc/clips/clip_01JGJHB6CEVFCQRYTVPM8DW892"
```

### Kick clip

URL: https://socialscrape.io/docs/api/kick/clip
Request: GET /v1/kick/clip
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Clip URL (kick.com/<user>/clips/clip_...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/kick/clip" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://kick.com/xqc/clips/clip_01JGJHB6CEVFCQRYTVPM8DW892"
```


## Snapchat

### Snapchat public profile

URL: https://socialscrape.io/docs/api/snapchat/profile
Request: GET /v1/snapchat/profile
Cost: 1 credit. Status: beta.

A public profile (snapchat.com/add/<handle>): name, bio, subscribers, public stories where shown.

Parameters:
- handle (string; required; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/snapchat/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=zane"
```

### Snapchat Spotlight video

URL: https://socialscrape.io/docs/api/snapchat/spotlight
Request: GET /v1/snapchat/spotlight
Cost: 1 credit. Status: beta.

One public Spotlight video by link: id, description, creator, engagement counts, thumbnail and content URL, where Snapchat shows them.

Parameters:
- url (url; required): Spotlight URL (snapchat.com/@user/spotlight/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/snapchat/spotlight" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.snapchat.com/@jack.scalise/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYb3djZ3FqY2VhAZXDhShdAZXDhPWfAAAAAQ"
```

### Snapchat Spotlight comments

URL: https://socialscrape.io/docs/api/snapchat/spotlight-comments
Request: GET /v1/snapchat/spotlight/comments
Cost: 1 credit. Status: beta.

Public comments on a Spotlight video; `parent` is the video. Pass the cursor back for more.

Parameters:
- url (url; required): Spotlight URL (snapchat.com/@user/spotlight/...).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/snapchat/spotlight/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.snapchat.com/@jack.scalise/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYb3djZ3FqY2VhAZXDhShdAZXDhPWfAAAAAQ"
```


## Linktree

### Linktree page

URL: https://socialscrape.io/docs/api/linktree/linktree
Request: GET /v1/linktree
Cost: 1 credit. Status: beta.

A Linktree page: the creator's name, bio, avatar, every link in page order and the social accounts it points to. Product and group links carry their type, thumbnail and price in `extra.link_details`; a published email is in `extra.emails` and `socials`. Pass the page `url` or just the `handle`.

Parameters:
- url (url; optional): Linktree page URL.
- handle (string; optional; also username): Linktree username.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linktree" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://linktr.ee/miguelangeles"
```


## Komi

### Komi page

URL: https://socialscrape.io/docs/api/komi/komi
Request: GET /v1/komi
Cost: 1 credit. Status: beta.

A Komi page: the creator's name, bio, avatar, every link in page order and the social accounts it points to. Hidden modules are left out; products carry their price in `extra.link_details`. Pass the page `url` or just the `handle`.

Parameters:
- url (url; optional): Komi page URL.
- handle (string; optional; also username): Komi username.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/komi" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://kimkardashian.komi.io/"
```


## Pillar

### Pillar page

URL: https://socialscrape.io/docs/api/pillar/pillar
Request: GET /v1/pillar
Cost: 1 credit. Status: beta.

A Pillar page: the creator's name, bio, avatar, every link in page order and the social accounts it points to. Links and products are listed together; the email is the one the creator shows on the page. Pass the page `url` or just the `handle`.

Parameters:
- url (url; optional): Pillar page URL.
- handle (string; optional; also username): Pillar username.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/pillar" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://pillar.io/angelstrife"
```


## Lnk.Bio

### Lnk.Bio page

URL: https://socialscrape.io/docs/api/linkbio/linkbio
Request: GET /v1/linkbio
Cost: 1 credit. Status: beta.

A Lnk.Bio page: the creator's name, bio, avatar, every link in page order and the social accounts it points to. Lnk.Bio only serves browser-like clients, so this one is slower. Pass the page `url` or just the `handle`.

Parameters:
- url (url; optional): Lnk.Bio page URL.
- handle (string; optional; also username): Lnk.Bio username.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkbio" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://lnk.bio/msjennafischer"
```


## Linkme

### Linkme page

URL: https://socialscrape.io/docs/api/linkme/linkme
Request: GET /v1/linkme
Cost: 1 credit. Status: beta.

A Linkme page: the creator's name, bio, avatar, every link in page order and the social accounts it points to. Contact emails come from the page's contact section. Pass the page `url` or just the `handle`.

Parameters:
- url (url; optional): Linkme page URL.
- handle (string; optional; also username): Linkme username.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkme" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://link.me/danucd"
```


## Creator contact details

### Find a creator's other social profiles

URL: https://socialscrape.io/docs/api/creators/social-profiles
Request: GET /v1/creators/social-profiles
Cost: 1 credit. Status: beta.

The social profiles a creator links from their own bio, links section or link-in-bio page, each as a profile with its platform and URL; `extra.evidence` lists the pages that say so and `extra.confidence` is 1.0 for a link on the profile itself, 0.9 for one a link-in-bio page or a linked profile declares. Only links the creator published are followed; nothing is guessed from a matching handle. Pass a `platform` and a bare `handle` (a leading @ is optional; YouTube also takes a channel id), or a profile `url`.

Parameters:
- url (url; optional): Profile URL on any supported platform.
- handle (string; optional; also username): Handle without a profile URL; needs `platform`.
- platform (string; optional; one of youtube, tiktok, instagram, twitter, twitch, facebook): Platform of `handle`.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/creators/social-profiles" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=MrBeast" \
  --data-urlencode "platform=youtube"
```

### Find a creator's public emails

URL: https://socialscrape.io/docs/api/creators/emails
Request: GET /v1/creators/emails
Cost: 1 credit. Status: beta.

Email addresses a creator published themselves, each with the URLs where it was seen (`extra.email_sources`, each typed social_profile, link_in_bio, linked_profile or website_page). Reads the creator's bio and links, the link-in-bio pages they link (Linktree, Komi, Pillar, Lnk.Bio, Linkme and other link hubs), the profiles they link, and up to three websites they declare (homepage and contact pages, robots.txt honoured). Addresses are never guessed or checked by sending mail; `kind` is business, management or personal when the address itself says so. `extra.partial` is true when a page failed or was skipped, so an empty result is then not proof that no address exists. Pass a `platform` and `handle`, or a profile `url`.

Parameters:
- url (url; optional): Profile URL on any supported platform.
- handle (string; optional; also username): Handle; needs `platform`.
- platform (string; optional; one of youtube, tiktok, instagram, twitter, twitch, facebook): Platform of `handle`.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/creators/emails" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "platform=instagram" \
  --data-urlencode "handle=miguelangeles"
```


## Facebook

### Facebook Ad Library search

URL: https://socialscrape.io/docs/api/facebook/ad-library-search
Request: GET /v1/facebook/ad-library/search
Cost: 1 credit. Status: beta.

Search the Meta Ad Library by keyword. `region` is the one country to search (ALL for every country). Also available as POST with a JSON body, for cursors too long for a URL.

Parameters:
- query (string; required; also keyword, q): Keyword to search for.
- sort (string; optional; one of relevance, impressions, newest; also sort_by, sortBy, order): Order of results: `impressions` is most impressions first (ScrapeCreators' default), `newest` is most recent. Changing it restarts the cursor chain.
- match (string; optional; one of any_words, exact_phrase; also search_type): Match any of the words, or the exact phrase.
- ad_type (string; optional; one of all, political): All ads, or only political and issue ads.
- language (string; optional; also lang): Only ads in this language, a 2-letter code (EN, ES, FR).
- status (string; optional; one of active, inactive, all; also active_status): Ad status.
- media_type (string; optional; one of all, image, video, meme, image_and_meme, none): Creative type. `meme` is Meta's word for text on an image.
- start_date (string; optional): Impressions window start, YYYY-MM-DD.
- end_date (string; optional): Impressions window end, YYYY-MM-DD.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nike" \
  --data-urlencode "region=US" \
  --data-urlencode "cursor=eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ"
```

### Facebook Ad Library search (POST body)

URL: https://socialscrape.io/docs/api/facebook/ad-library-search-post
Request: POST /v1/facebook/ad-library/search
Cost: 1 credit. Status: beta.

The same as the GET form, with the parameters in a JSON body.

Parameters:
- query (string; required; also keyword, q): Keyword to search for.
- sort (string; optional; one of relevance, impressions, newest; also sort_by, sortBy, order): Order of results: `impressions` is most impressions first (ScrapeCreators' default), `newest` is most recent. Changing it restarts the cursor chain.
- match (string; optional; one of any_words, exact_phrase; also search_type): Match any of the words, or the exact phrase.
- ad_type (string; optional; one of all, political): All ads, or only political and issue ads.
- language (string; optional; also lang): Only ads in this language, a 2-letter code (EN, ES, FR).
- status (string; optional; one of active, inactive, all; also active_status): Ad status.
- media_type (string; optional; one of all, image, video, meme, image_and_meme, none): Creative type. `meme` is Meta's word for text on an image.
- start_date (string; optional): Impressions window start, YYYY-MM-DD.
- end_date (string; optional): Impressions window end, YYYY-MM-DD.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/facebook/ad-library/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike"}'
```

### Facebook Ad Library ads by page

URL: https://socialscrape.io/docs/api/facebook/ad-library-company-ads
Request: GET /v1/facebook/ad-library/company/ads
Cost: 1 credit. Status: beta.

The ads a company runs, by Ad Library page id or by company name. Also available as POST with a JSON body.

Parameters:
- id (string; optional; also pageId, page_id): Ad Library page id of the advertiser (from advertiser search).
- company_name (string; optional; also companyName): Advertiser name (resolved to a page id).
- status (string; optional; one of active, inactive, all; also active_status): Ad status.
- media_type (string; optional; one of all, image, video, meme, image_and_meme, none): Creative type. `meme` is Meta's word for text on an image.
- language (string; optional; also lang): Only ads in this language, a 2-letter code (EN, ES, FR).
- sort (string; optional; one of relevance, impressions, newest; also sort_by, sortBy, order): Order of results: `impressions` is most impressions first (ScrapeCreators' default), `newest` is most recent. Changing it restarts the cursor chain.
- start_date (string; optional): Impressions window start, YYYY-MM-DD.
- end_date (string; optional): Impressions window end, YYYY-MM-DD.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/company/ads" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=15087023444" \
  --data-urlencode "region=US" \
  --data-urlencode "cursor=eyJrIjoiZmJhZHMiLCJjIjoiQVFIVEZfamZkd1hQZjYwUk9Ld3A0Qk1QeGlCM1BiN2pxYkc3dEtlbEhXSmJMc3hnb29XbnFjbWRnUUJCMEJ0Y3RGcW8iLCJwIjoiMTUwODcwMjM0NDQifQ"
```

### Facebook Ad Library ads by page (POST body)

URL: https://socialscrape.io/docs/api/facebook/ad-library-company-ads-post
Request: POST /v1/facebook/ad-library/company/ads
Cost: 1 credit. Status: beta.

The same as the GET form, with the parameters in a JSON body.

Parameters:
- id (string; optional; also pageId, page_id): Ad Library page id of the advertiser (from advertiser search).
- company_name (string; optional; also companyName): Advertiser name (resolved to a page id).
- status (string; optional; one of active, inactive, all; also active_status): Ad status.
- media_type (string; optional; one of all, image, video, meme, image_and_meme, none): Creative type. `meme` is Meta's word for text on an image.
- language (string; optional; also lang): Only ads in this language, a 2-letter code (EN, ES, FR).
- sort (string; optional; one of relevance, impressions, newest; also sort_by, sortBy, order): Order of results: `impressions` is most impressions first (ScrapeCreators' default), `newest` is most recent. Changing it restarts the cursor chain.
- start_date (string; optional): Impressions window start, YYYY-MM-DD.
- end_date (string; optional): Impressions window end, YYYY-MM-DD.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/facebook/ad-library/company/ads" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"15087023444"}'
```

### Facebook Ad Library ad details

URL: https://socialscrape.io/docs/api/facebook/ad-library-ad
Request: GET /v1/facebook/ad-library/ad
Cost: 1 credit. Status: beta.

One ad by id or URL: page, status, dates and the snapshot (text, images, videos, format, link, call to action). Regulated ads add their transparency data in `extra`.

Parameters:
- id (string; optional; also ad_id, adId): Ad id in the library.
- url (url; optional): Ad Library URL (facebook.com/ads/library/?id=...).
- get_transcript (boolean; optional): Accepted for compatibility. A video ad's transcript is its own call, `ad/transcript` (AI transcription, metered); this flag only adds a pointer to it in `extra.transcript_hint`.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/ad" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=352695862528588"
```

### Facebook Ad Library ad transcript

URL: https://socialscrape.io/docs/api/facebook/ad-library-ad-transcript
Request: GET /v1/facebook/ad-library/ad/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Transcript of a video ad. Ad Library videos carry no caption tracks, so this is always AI transcription of the audio, billed by the length of the audio. An ad with no video answers an unbilled error.

Parameters:
- id (string; optional; also ad_id, adId): Ad id in the library.
- url (url; optional): Ad Library URL (facebook.com/ads/library/?id=...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/ad/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=352695862528588"
```

### Facebook Ad Library advertiser search

URL: https://socialscrape.io/docs/api/facebook/ad-library-search-companies
Request: GET /v1/facebook/ad-library/search/companies
Cost: 1 credit. Status: beta.

Advertisers matching a name: Ad Library page id, category, likes, verification and Instagram details. Use the page id with `company/ads`. Meta closes its advertiser typeahead to logged-out visitors, so these are the pages behind the ads a search for the name returns (up to 10, name matches first), each completed from the ad-details query; `ad_count` is not available.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/ad-library/search/companies" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nike"
```


## Google

### Google Ads Transparency advertiser search

URL: https://socialscrape.io/docs/api/google/ad-library-advertisers-search
Request: GET /v1/google/ad-library/advertisers/search
Cost: 1 credit. Status: beta.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/google/ad-library/advertisers/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nike" \
  --data-urlencode "region=US"
```

### Google Ads Transparency ads by advertiser

URL: https://socialscrape.io/docs/api/google/ad-library-company-ads
Request: GET /v1/google/ad-library/company/ads
Cost: 1 credit. Status: beta.

An advertiser's public ads by advertiser id or website domain: ids, previews and first and last shown dates when Google gives them.

Parameters:
- id (string; optional; also advertiser_id, advertiserId): Advertiser id (AR...).
- domain (string; optional): Advertiser's website domain.
- topic (string; optional; one of all, political): All ads or political ads. Political needs a `region`.
- platform (string; optional; one of google_maps, google_play, google_search, google_shopping, youtube): Where the ad ran.
- format (string; optional; one of all, text, image, video): Creative format.
- start_date (string; optional): Ads shown from this date, YYYY-MM-DD.
- end_date (string; optional): Ads shown up to this date, YYYY-MM-DD.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/google/ad-library/company/ads" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=AR16735076323512287233" \
  --data-urlencode "platform=youtube" \
  --data-urlencode "region=US"
```

### Google Ads Transparency ad details

URL: https://socialscrape.io/docs/api/google/ad-library-ad
Request: GET /v1/google/ad-library/ad
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Creative URL (adstransparency.google.com/advertiser/AR.../creative/CR...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/google/ad-library/ad" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://adstransparency.google.com/advertiser/AR16735076323512287233/creative/CR17814369753519620097"
```


## LinkedIn

### LinkedIn Ad Library search

URL: https://socialscrape.io/docs/api/linkedin/ad-library-search
Request: GET /v1/linkedin/ad-library/search
Cost: 1 credit. Status: beta.

Search the LinkedIn Ad Library by company name, company id or keyword (give at least one). Custom dates need both `start_date` and `end_date`, within the past year and ending yesterday at the latest. `countries` is a comma-separated list; the cursor is LinkedIn's pagination token.

Parameters:
- query (string; optional; also keyword, q): Keyword to search for.
- company (string; optional; also company_name): Advertiser name.
- company_id (string; optional; also companyId): LinkedIn company id: the number in linkedin.com/company/<id>.
- countries (string; optional): Comma-separated 2-letter countries, "US,CA,MX".
- start_date (string; optional; also startDate): Start date, YYYY-MM-DD. Use with `end_date`.
- end_date (string; optional; also endDate): End date, YYYY-MM-DD. Use with `start_date`.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/ad-library/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "company=Microsoft"
```

### LinkedIn Ad Library ad details

URL: https://socialscrape.io/docs/api/linkedin/ad-library-ad
Request: GET /v1/linkedin/ad-library/ad
Cost: 1 credit. Status: beta.

Parameters:
- url (url; optional): Ad URL (linkedin.com/ad-library/detail/...).
- id (string; optional; also ad_id, adId): Ad id in the library.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/ad-library/ad" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1662766106"
```


## TikTok

### TikTok Ad Library search

URL: https://socialscrape.io/docs/api/tiktok/ad-library-search
Request: GET /v1/tiktok/ad-library/search
Cost: 1 credit. Status: beta.

Search TikTok's public Ads Library by keyword (`query`, or a quoted "exact phrase") or by advertiser (`advertiser_name`, resolved through TikTok's typeahead). Give one of the two. The library is TikTok's European commercial-content library: it lists ads shown in the EU, EEA, UK and Switzerland, 12 per page, newest shown first. `region` is one of those countries (default all).

Parameters:
- query (string; optional; also keyword, q): General ad search.
- advertiser_name (string; optional): Advertiser name to resolve and search by advertiser entity.
- adv_biz_ids (string; optional): TikTok advertiser business id from a See all ads link; pins the exact advertiser. Only works together with `advertiser_name`.
- start_date (string; optional): Ads shown from this date, YYYY-MM-DD (default: a year before `end_date`).
- end_date (string; optional): Ads shown up to this date, YYYY-MM-DD (default: today).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/ad-library/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query="free trial"" \
  --data-urlencode "start_date=2026-10-22" \
  --data-urlencode "end_date=2026-10-29"
```

### TikTok Ad Library ad details

URL: https://socialscrape.io/docs/api/tiktok/ad-library-ad
Request: GET /v1/tiktok/ad-library/ad
Cost: 1 credit. Status: beta.

One ad from TikTok's European Ads Library: the creative, the advertiser (business id, registry country) and the targeting with impressions by region, age and gender, as the library shows them.

Parameters:
- id (string; optional; also ad_id, adId): Ad id in the library.
- url (url; optional): Ad URL (library.tiktok.com/ads/detail/?ad_id=...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/ad-library/ad" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1879687389944914"
```


## X (Twitter)

### X post search

URL: https://socialscrape.io/docs/api/twitter/search-posts
Request: GET /v1/twitter/search/posts
Cost: 1 credit. Status: beta.

Public posts found through a web search engine (DuckDuckGo, restricted to x.com), then read like `tweet` through X's public post widget, so views, retweet and bookmark counts are missing. This is engine-indexed discovery, not X's own search (which needs a login): coverage is incomplete, recent posts can be missing and the order is the engine's. Deleted, protected and unreachable posts are left out. Cursor pages 1 to 11.

Parameters:
- query (string; required; also keyword, q): Keyword or phrase to look for in public X posts.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/search/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=ai agents"
```

### X profile

URL: https://socialscrape.io/docs/api/twitter/profile
Request: GET /v1/twitter/profile
Cost: 1 credit. Status: beta.

Public account details as X shows them to logged-out visitors: bio, links, avatar, banner, followers, following, post count and verification. X no longer shows logged-out visitors the account's likes or listed counts, so `stats.likes` is empty. Suspended accounts answer removed, unknown ones not_found.

Parameters:
- handle (string; required; also username, screen_name): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=@jack"
```

### X profile posts

URL: https://socialscrape.io/docs/api/twitter/profile-tweets
Request: GET /v1/twitter/profile/tweets
Cost: 1 credit. Status: beta.

Public posts of an account, as X shows them to logged-out visitors: about 20 popular posts and reposts, or, when X's public timeline widget is rate limited, the 5 newest original posts. X offers logged-out visitors no way to page further, so there is no next-page cursor.

Parameters:
- handle (string; required; also username, screen_name): Username, with or without the leading @.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/profile/tweets" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=NASA"
```

### X post details

URL: https://socialscrape.io/docs/api/twitter/tweet
Request: GET /v1/twitter/tweet
Cost: 1 credit. Status: beta.

One public post with its counts, media and, for a quote post, the quoted post (`extra.quoted_post`). If X will not serve the post page, the answer comes from X's public post widget instead and views, retweet and bookmark counts are missing (`extra.source_shape` is `syndication`).

Parameters:
- url (url; optional): Post URL (x.com/<user>/status/<id>).
- id (string; optional; also tweet_id): Post id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/tweet" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://x.com/jack/status/20"
```

### X video transcript

URL: https://socialscrape.io/docs/api/twitter/tweet-transcript
Request: GET /v1/twitter/tweet/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

AI transcription of the video in a post. Videos over 2 minutes need allow_long_transcription=true and cost 1 credit per started minute. Posts without video, and animated GIFs, answer transcript_unavailable (free).

Parameters:
- url (url; optional): Post URL (x.com/<user>/status/<id>).
- id (string; optional; also tweet_id): Post id.
- allow_long_transcription (boolean; optional): Transcribe videos longer than 2 minutes too.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/tweet/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://x.com/yashsrivasta7a/status/2111731581702598777"
```

### X community

URL: https://socialscrape.io/docs/api/twitter/community
Request: GET /v1/twitter/community
Cost: 1 credit. Status: beta.

Parameters:
- url (url; optional): Community URL (x.com/i/communities/<id>).
- id (string; optional; also community_id): Community id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/community" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1926186499399139650"
```

### X community posts

URL: https://socialscrape.io/docs/api/twitter/community-tweets
Request: GET /v1/twitter/community/tweets
Cost: 1 credit. Status: beta.

The posts X shows logged-out visitors on a community page: its 20 most-liked posts. There is no next-page cursor.

Parameters:
- url (url; optional): Community URL (x.com/i/communities/<id>).
- id (string; optional; also community_id): Community id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/twitter/community/tweets" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://x.com/i/communities/1926186499399139650"
```


## Facebook

### Facebook profile or page

URL: https://socialscrape.io/docs/api/facebook/profile
Request: GET /v1/facebook/profile
Cost: 1 credit. Status: beta.

A public page: category, address, email, phone, website, services, price range, rating, likes and followers (`talking_about` only when Facebook shows it), plus its ad library page id.

Parameters:
- url (url; required): Profile or page URL.
- get_business_hours (boolean; optional): Include the business hours.
- include_gated_profile (boolean; optional): Return limited public fields for gated or age-restricted pages. Ignored for normal public pages.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/NASA"
```

### Facebook profile posts

URL: https://socialscrape.io/docs/api/facebook/profile-posts
Request: GET /v1/facebook/profile/posts
Cost: 1 credit. Status: beta.

Public posts of a page, 3 a page: text, reactions, comments, time, video URLs and top comments.

Parameters:
- url (url; optional): Profile or page URL.
- id (string; optional; also pageId, page_id): The profile or page id, as `profile` returns it in `id`.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/NASA"
```

### Facebook profile reels

URL: https://socialscrape.io/docs/api/facebook/profile-reels
Request: GET /v1/facebook/profile/reels
Cost: 1 credit. Status: beta.

Up to 10 reels a page: id, URL, view count (Facebook's rounded public badge, so 27K becomes 27000), description, time, video URL, duration and music. For exact counts, call `post` per reel.

Parameters:
- url (url; required): Profile or page URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/profile/reels" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/nike"
```

### Facebook profile photos

URL: https://socialscrape.io/docs/api/facebook/profile-photos
Request: GET /v1/facebook/profile/photos
Cost: 1 credit. Status: beta.

Photos from a page's Photos tab (type "image"): id, caption, image URL and size. The cursor carries both of ScrapeCreators' paging values (`next_page_id` and `cursor`).

Parameters:
- url (url; required): Profile or page URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/profile/photos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/NASA" \
  --data-urlencode "cursor=eyJrIjoicGhvdG9zIiwiY29sIjoiWVhCd1gyTnZiR3hsWTNScGIyNDZjR1ppYVdRd00yNUtURUo0ZGs1U01WZzVTRTVFUkZseFp6aERNamN5UVdKWmRFcHJlbUpuZW5OMFEzbE9hR1pFVldOR05rNUtlRTQwVFdoSFIyNWpkRmszV1dsNE5VUmFiMFJRV1RoclJIbFdibEZpVEcxaE9UVm5jVGRTUms0NFRtUnMiLCJhZnRlciI6IkFRSFR4Tl81dXUtMGFtdDR5NzRYM0hQbGVncy1CSVI4X21MVUxRQnk3dFM3OXQtLWVBb2d1dnZXMGRhU0ZnMElXd1FZUHRUMHVVeHN5cWRmeVFXSktwM2ZudyIsInUiOiJodHRwczovL3d3dy5mYWNlYm9vay5jb20vTkFTQSJ9"
```

### Facebook page events

URL: https://socialscrape.io/docs/api/facebook/profile-events
Request: GET /v1/facebook/profile/events
Cost: 1 credit. Status: beta.

Public events of a page.

Parameters:
- url (url; required): Profile or page URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/profile/events" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/brickyardoldtown"
```

### Facebook video search

URL: https://socialscrape.io/docs/api/facebook/search-videos
Request: GET /v1/facebook/search/videos
Cost: 1 credit. Status: beta.

Facebook's own public video search, logged out: matching videos and reels in Facebook's ranking. Not exhaustive; can take several seconds. Keep the query unchanged while paging.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/search/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=nasa"
```

### Facebook post details

URL: https://socialscrape.io/docs/api/facebook/post
Request: GET /v1/facebook/post
Cost: 1 credit. Status: beta.

One public post or reel: text, counts, reactions, media and the `feedback_id` that makes `post/comments` faster. Call it per reel for exact like, comment and view counts (Facebook shows a logged-out visitor no share count on a video page; `profile/posts` has it).

Parameters:
- url (url; required): Post, video or reel URL.
- get_transcript (boolean; optional): Include the video's existing captions in `extra.transcript` (none if it has none; `post/transcript` also transcribes the audio with AI).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/reel/2166091230582141/"
```

### Facebook video transcript

URL: https://socialscrape.io/docs/api/facebook/post-transcript
Request: GET /v1/facebook/post/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Transcript of a video post or reel: existing captions first, otherwise AI transcription of the audio.

Parameters:
- url (url; required): Post, video or reel URL.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/post/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/reel/1803909017420449/"
```

### Facebook post comments

URL: https://socialscrape.io/docs/api/facebook/post-comments
Request: GET /v1/facebook/post/comments
Cost: 1 credit. Status: beta.

Comments on a post or reel: text, time, reply and reaction counts, author and attachments.

Parameters:
- url (url; optional): Post, video or reel URL.
- feedback_id (string; optional): The post's feedback id (from `post`); using it instead of `url` makes the request much faster.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/post/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/reel/2166091230582141/"
```

### Facebook comment replies

URL: https://socialscrape.io/docs/api/facebook/post-comment-replies
Request: GET /v1/facebook/post/comment/replies
Cost: 1 credit. Status: beta.

Replies to one comment. Either the post `url` and the parent `comment_id`, or the comment's `feedback_id` and `expansion_token` as the comments list returns them (both are needed).

Parameters:
- url (url; optional): Post, video or reel URL.
- comment_id (string; optional; also commentId): Id of the parent comment.
- feedback_id (string; optional): The comment's feedback id (not the comment id), from `post/comments`.
- expansion_token (string; optional): The comment's expansion token, from `post/comments`.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/post/comment/replies" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/reel/2166091230582141/" \
  --data-urlencode "comment_id=2082653245809386"
```

### Facebook public group

URL: https://socialscrape.io/docs/api/facebook/group
Request: GET /v1/facebook/group
Cost: 1 credit. Status: beta.

What a public group's About page shows: description, privacy, member and activity counts, categories, admins and moderators where shown, history and rules.

Parameters:
- url (url; optional): Public group URL (facebook.com/groups/...). Sub-pages such as /about work too.
- id (string; optional; also group_id): Numeric group id; use it instead of `url` if you have it.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/group" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/groups/366190054572553"
```

### Facebook public group posts

URL: https://socialscrape.io/docs/api/facebook/group-posts
Request: GET /v1/facebook/group/posts
Cost: 1 credit. Status: beta.

Posts of a public group, 3 a page, chronological by default.

Parameters:
- url (url; optional): Public group URL (facebook.com/groups/...). Sub-pages such as /about work too.
- id (string; optional; also group_id): Numeric group id; use it instead of `url` if you have it.
- sort (string; optional; one of chronological, top, recent_activity, chronological_listings; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/group/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/groups/366190054572553"
```

### Facebook Marketplace location search

URL: https://socialscrape.io/docs/api/facebook/marketplace-location-search
Request: GET /v1/facebook/marketplace/location/search
Cost: 1 credit. Status: beta.

Marketplace cities and areas matching a name, with the coordinates to pass to `marketplace/search` as `lat` and `lng`.

Parameters:
- query (string; required; also keyword, q): City or area name.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/marketplace/location/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=Austin"
```

### Facebook Marketplace search

URL: https://socialscrape.io/docs/api/facebook/marketplace-search
Request: GET /v1/facebook/marketplace/search
Cost: 1 credit. Status: beta.

Search Marketplace by keyword, or browse a category without a keyword. Needs a place: `lat` and `lng` (see `marketplace/location/search`) or a `location` name. About 24 listings a page; keep the inputs unchanged while paging and de-duplicate by listing id.

Parameters:
- query (string; optional; also keyword, q): Search keyword. Required unless `category_id` is given.
- location (string; optional): City or area to search around ("Austin, TX").
- lat (number; optional; also latitude): Latitude of the search centre.
- lng (number; optional; also longitude): Longitude of the search centre.
- category_id (string; optional): Marketplace category id. Without a keyword only these browse: Antiques 393860164117441, Appliances 678754142233400, Bicycles 1658310421102081, Boats 712638205822882, Electronics 1792291877663080, Furniture 1583634935226685, Garden 800089866739547, Household 1569171756675761, Tools 1670493229902393, Trailers 655837954899686, Vehicles 807311116002614 (or 546583916084032). Other ids need a keyword.
- radius_km (number; optional; also radius): Search radius in km.
- min_price (number; optional): Lowest listing price.
- max_price (number; optional): Highest listing price.
- sort (string; optional; one of relevance, distance, newest, price_low, price_high; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- delivery_method (string; optional; one of all, local_pickup, shipping): Delivery filter.
- condition (string; optional; one of new, used_like_new, used_good, used_fair): Condition filter.
- date_listed (string; optional; one of all, day, week, month): Listed within. Uses the UI's calendar-day buckets.
- availability (string; optional; one of available, sold, all): Availability filter.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/marketplace/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=bike" \
  --data-urlencode "lat=30.2672" \
  --data-urlencode "lng=-97.7431" \
  --data-urlencode "cursor=eyJrIjoibWFya2V0IiwibGF0IjozMC4yNjcyLCJsbmciOi05Ny43NDMxLCJhZnRlciI6IntcInBnXCI6MCxcImIyY1wiOntcImJyXCI6XCJcIixcIml0XCI6MCxcImhtc3JcIjpmYWxzZSxcInRiaVwiOjB9LFwiYzJjXCI6e1wiYnJcIjpcIkFicGxreFpHQmZ2R0M1a1ZXbV81Q1F2RFdUdTNRSm9sMnI4NmJtZG1yNEdrZW1PTVFXemdJTERXbHNJSTlBaU92WGdWRFoyLVFvZDRlNDdSNFFDM2Zjd2JvRUNyWjBKTXJxVm9jckNxUGJMdjVXV3U2NDJOS25zR1pCMEVkNl9kaE5NTWgxeXNUbXhrSzYxeWxFQmFIUnRkNTdZX0dxY3hkTVdUTFgtaXh6NE5BNkNGVUtoTlZzQUN1SXZIQXFleHA4OFdnWXZ2VE5OYTJ1YzJXMHo1Y3E1SC1NZmlrR291MmpIQjM3YXRobm9rclo5UTlVTmlpNmtqME5tNTRuNTJUUF83cUJ5UkowdWhVWDVtUWh3Y0pqdWoxdjBGWjQwVU1iLVdXTnNNUUNWVFlKYkM0ZXhrWFVEb0xES0YxVG8wdmFTajhoVVpyOWxhZ0c2ZTJBN212Z196eFpBdWJ4ODRLQUhpTmxrNFliQ3pFZXhsSFdVbmdlQk1QVFlIUkhVQ19Ucm9mZ204NG5GLTRodGxzbXNFdWpsTmd0VEtMbkxfVmQ5OFVLZXpHS0tzbnVnT1lsZUdJbmVoZV9oTE5XdGFvb2Y4dDBEc2hVc0NIbWFLNFFTNUxXNWhraFZaRXlsN0lVT1JWVWxYbFpqQnlaMHBYM3RmT0NaU2twaUwtRzdKelJhU0FqR1U0QlBXd2xZM2hpR2U0dDE3Y1NwZS1Na1BWZmR6cTJnRXlzazV5TlRZckg5QUN4ZlE0R01CMW9kaWs4c1wiLFwiaXRcIjoxMyxcInJwYnJcIjpcIlwiLFwicnBoclwiOmZhbHNlLFwicm1oclwiOmZhbHNlLFwic3NpXCI6ZmFsc2UsXCJzc2NvXCI6MCxcInNzcGlcIjpbXCI0MDAzNzA0OTI1OTIyNjcxMFwiLFwiMzkyNzgxODM4NzUxNTgxNjlcIixcIjI5NDQxMzYxMjQyMTE1NDA5XCIsXCIyODg5NDQ1NjgyNjkxMzc5NFwiLFwiMjgxOTkwNTUzOTk3NzIwNjNcIixcIjI4ODM5MDQ1Mjk1Njk2ODI3XCIsXCIyNzkzMzM1NzU2NjMwNDQ2MlwiLFwiMjg3MDk2ODY3NjUzNTk1ODVcIixcIjI4MzcwODkxMTQ1OTMwNjExXCIsXCIyODM0NzQ3NDUxODIwNDYzMVwiLFwiMjg2MDk0NzE0ODIwMTY3OTRcIixcIjI4MzUxMzkxOTExMjE3MzI5XCIsXCIyODI4MjM5ODM2NDY5ODc1OVwiXX0sXCJpcnJcIjpmYWxzZSxcInNlcnBfY3RhXCI6ZmFsc2UsXCJydWlcIjpbXSxcIm1waWRcIjpbXSxcInNzaWNcIjowLFwidWJwXCI6bnVsbCxcIm5jcm5kXCI6MCxcImlyc3JcIjpmYWxzZSxcImJtcHJcIjpbXSxcImJtcGVpZFwiOltdLFwibm1ibXBcIjpmYWxzZSxcInNrcnJcIjpmYWxzZSxcImlvb3VyXCI6ZmFsc2UsXCJpc2VcIjpmYWxzZSxcInNtc19jdXJzb3JcIjp7XCJwYWdlX2luZGV4XCI6MCxcImJsZW5kZWRfYWRfaW5kZXhcIjowLFwib3JnYW5pY3Nfc2luY2VfbGFzdF9hZFwiOjAsXCJwYWdlX29yZ2FuaWNfY291bnRcIjowLFwiYmxlbmRlZF9vcmdhbmljX2luZGV4XCI6MCxcInJldHVybmVkX2FkX2luZGV4XCI6MCxcInRvdGFsX2luZGV4XCI6MH19In0"
```

### Facebook Marketplace listing

URL: https://socialscrape.io/docs/api/facebook/marketplace-item
Request: GET /v1/facebook/marketplace/item
Cost: 1 credit. Status: beta.

One listing: title, description, price, location, condition, photos, seller and availability flags.

Parameters:
- url (url; optional): Listing URL (facebook.com/marketplace/item/<id>).
- id (string; optional; also item_id): Listing id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/marketplace/item" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1114608241188932"
```

### Facebook Events search

URL: https://socialscrape.io/docs/api/facebook/events-search
Request: GET /v1/facebook/events/search
Cost: 1 credit. Status: beta.

Events matching a name or description, as facebook.com/events/search shows them to a logged-out visitor (about 7 on the first page). There is no logged-out place filter: `location` is searched as words after the query.

Parameters:
- query (string; required; also keyword, q): Search terms.
- location (string; optional): City or area to search around ("Austin, TX").
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/events/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=jazz jam"
```

### Facebook city events

URL: https://socialscrape.io/docs/api/facebook/events
Request: GET /v1/facebook/events
Cost: 1 credit. Status: beta.

The events Facebook lists for a city, from its public explore page.

Parameters:
- url (url; required): City events page (facebook.com/events/explore/<city>/<id>).
- time (string; optional; one of today, this_week, next_week): Time frame; default all time.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/events" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547"
```

### Facebook event details

URL: https://socialscrape.io/docs/api/facebook/event
Request: GET /v1/facebook/event
Cost: 1 credit. Status: beta.

Parameters:
- url (url; optional): Event URL (facebook.com/events/<id>).
- id (string; optional; also event_id): Event id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/facebook/event" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=437638146356948"
```


## LinkedIn

### LinkedIn public person profile

URL: https://socialscrape.io/docs/api/linkedin/profile
Request: GET /v1/linkedin/profile
Cost: 1 credit. Status: beta.

What LinkedIn shows a signed-out visitor on a public profile page: name, headline, location, about, followers, experience, education, skills, courses, recommendations, articles, recent public posts and similar profiles. A member who hides the public profile answers not_found.

Parameters:
- url (url; required): Profile URL (linkedin.com/in/<slug>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.linkedin.com/in/williamhgates"
```

### LinkedIn company page

URL: https://socialscrape.io/docs/api/linkedin/company
Request: GET /v1/linkedin/company
Cost: 1 credit. Status: beta.

A company page as a signed-out visitor sees it: description, website, industry, size, headquarters, specialties, locations, followers, employee count, affiliated and similar pages.

Parameters:
- url (url; required): Company page URL (linkedin.com/company/<slug>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/company" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.linkedin.com/company/microsoft"
```

### LinkedIn company posts

URL: https://socialscrape.io/docs/api/linkedin/company-posts
Request: GET /v1/linkedin/company/posts
Cost: 1 credit. Status: beta.

The latest public posts and reposts on a company page (up to 10): URL, id, date, full text, media, reactions and comment counts. LinkedIn shows signed-out visitors only this block; the posts tab and later pages need a login, so the cursor is always null.

Parameters:
- url (url; required): Company page URL (linkedin.com/company/<slug>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/company/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.linkedin.com/company/microsoft"
```

### LinkedIn public post

URL: https://socialscrape.io/docs/api/linkedin/post
Request: GET /v1/linkedin/post
Cost: 1 credit. Status: beta.

A public post: full text, author, date, reactions and comment counts, media (video, images, shared article) and the top public comments. Also reads /feed/update/urn:li:activity:... and Pulse (/pulse/...) article URLs.

Parameters:
- url (url; required): Post URL (linkedin.com/posts/... or /feed/update/urn:li:activity:...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.linkedin.com/posts/jeffweiner08_seeing-lots-of-content-about-dolly-parton-activity-7499148115615350784-j-4g"
```

### LinkedIn post video transcript

URL: https://socialscrape.io/docs/api/linkedin/post-transcript
Request: GET /v1/linkedin/post/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

The transcript of a post's video when LinkedIn shows one publicly; otherwise AI transcription of the video's audio.

Parameters:
- url (url; required): Post URL (linkedin.com/posts/...).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/linkedin/post/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.linkedin.com/feed/update/urn:li:activity:7520503284458147840"
```


## TikTok

### TikTok Shop product search

URL: https://socialscrape.io/docs/api/tiktok/shop-search
Request: GET /v1/tiktok/shop/search
Cost: 1 credit. Status: beta.

Products matching a search, each with price, rating, sold count and shop. Pages of 20 by cursor; TikTok decides how deep a query goes (past 40 results when it has them). US catalogue only.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/shop/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=water bottle" \
  --data-urlencode "region=US" \
  --data-urlencode "cursor=eyJxIjoid2F0ZXIgYm90dGxlIiwibyI6MjAsInB0IjoiMjAyNjEwMzAwMTUzNTgzOTBGN0E3ODNCMURFNzJGODNGNiJ9"
```

### TikTok Shop products of a shop

URL: https://socialscrape.io/docs/api/tiktok/shop-products
Request: GET /v1/tiktok/shop/products
Cost: 1 credit. Status: beta.

Every product of one shop; `parent` is the shop's profile (first page). 20 products a page in TikTok's own order, which puts a shop's best sellers first. `sort=new_releases` reads the whole catalogue (up to 120 products) and orders it newest first by product id, so it ignores the cursor and returns one page. US catalogue only.

Parameters:
- url (url; required): Shop URL (tiktok.com/shop/store/<name>/<id>).
- sort (string; optional; one of top, new_releases; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/shop/products" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.tiktok.com/shop/store/goli-nutrition/7495794203056835079"
```

### TikTok Shop product details

URL: https://socialscrape.io/docs/api/tiktok/shop-product
Request: GET /v1/tiktok/shop/product
Cost: 1 credit. Status: beta.

One product with its SKUs and stock levels (in `extra`), rating, rating spread, specifications and shipping. US catalogue only. TikTok sometimes treats an exit as a crawler; the request is retried on fresh exits and answers `upstream_blocked` (free) if all three are refused.

Parameters:
- url (url; optional): Product URL (tiktok.com/shop/pdp/...).
- id (string; optional; also product_id): Product id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/shop/product" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1729527313880355335"
```

### TikTok Shop product reviews

URL: https://socialscrape.io/docs/api/tiktok/shop-product-reviews
Request: GET /v1/tiktok/shop/product/reviews
Cost: 1 credit. Status: beta.

Customer reviews of a product, newest first: rating, text, photos, the reviewer's masked name and the variant bought. 5 a page. The first page is always available; later pages depend on TikTok accepting the exit and answer `upstream_blocked` (free) when it does not.

Parameters:
- url (url; optional): Product URL (tiktok.com/shop/pdp/...).
- id (string; optional; also product_id): Product id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/tiktok/shop/product/reviews" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1729527313880355335"
```


## Amazon

### Amazon storefront products

URL: https://socialscrape.io/docs/api/amazon/shop
Request: GET /v1/amazon/shop
Cost: 1 credit. Status: beta.

Products featured on an Amazon creator storefront, each ASIN once, with the lists, photos and videos that feature it in `extra.posts`. The first page also carries the creator's trending picks (with prices) and `parent`: the creator's profile with socials, curations and lists. 20 posts a page. Creator storefronts only (amazon.com/shop/<name>); brand stores (amazon.com/stores/...) are not supported. The creator's affiliate tags are removed from every URL.

Parameters:
- url (url; required): Storefront URL (amazon.com/shop/<name>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/amazon/shop" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.amazon.com/shop/sydneydelrey"
```


## Spotify

### Spotify artist

URL: https://socialscrape.io/docs/api/spotify/artist
Request: GET /v1/spotify/artist
Cost: 1 credit. Status: beta.

Followers, monthly listeners, world rank, top cities, bio, links, top tracks, albums, singles, related artists and playlists (in `extra`). Spotify has no handles: `id` is the 22 character id.

Parameters:
- url (url; optional): Spotify artist URL.
- id (string; optional): Spotify artist id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/artist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=06HL4z0CvFAxyc27GXpf02"
```

### Spotify album

URL: https://socialscrape.io/docs/api/spotify/album
Request: GET /v1/spotify/album
Cost: 1 credit. Status: beta.

The album with its tracks (up to 200), label, copyright and release date.

Parameters:
- url (url; optional): Spotify album URL.
- id (string; optional): Spotify album id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/album" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=5AEDGbliTTfjOB8TSm1sxt"
```

### Spotify track

URL: https://socialscrape.io/docs/api/spotify/track
Request: GET /v1/spotify/track
Cost: 1 credit. Status: beta.

Title, artists, album, duration, lifetime play count and the 30 second preview URL.

Parameters:
- url (url; optional): Spotify track URL.
- id (string; optional): Spotify track id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/track" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=4cOdK2wGLETKBW3PvgPWqT"
```

### Spotify podcast

URL: https://socialscrape.io/docs/api/spotify/podcast
Request: GET /v1/spotify/podcast
Cost: 1 credit. Status: beta.

A show's details (kind "podcast").

Parameters:
- url (url; optional): Spotify show URL.
- id (string; optional): Spotify show id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/podcast" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=4rOoJ6Egrf8K2IrywzwOMk"
```

### Spotify playlist

URL: https://socialscrape.io/docs/api/spotify/playlist
Request: GET /v1/spotify/playlist
Cost: 1 credit. Status: beta.

A public playlist's tracks, 50 a page; `parent` is the playlist. Pass the cursor back until it is null.

Parameters:
- url (url; optional): Spotify playlist URL.
- id (string; optional): Spotify playlist id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/playlist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=37i9dQZF1DX4UtSsGT1Sbe"
```

### Spotify podcast episodes

URL: https://socialscrape.io/docs/api/spotify/podcast-episodes
Request: GET /v1/spotify/podcast/episodes
Cost: 1 credit. Status: beta.

A show's episodes, 20 a page, in the order Spotify lists them (type "episode"); `parent` is the show. Pass the cursor back until it is null.

Parameters:
- url (url; optional): Spotify show URL.
- id (string; optional): Spotify show id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/podcast/episodes" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=4rOoJ6Egrf8K2IrywzwOMk"
```

### Spotify search

URL: https://socialscrape.io/docs/api/spotify/search
Request: GET /v1/spotify/search
Cost: 1 credit. Status: beta.

Tracks, artists, albums, playlists, podcasts, episodes and audiobooks. Without `type` every kind is returned, 10 of each; with `type`, 20 of that kind. Use `type=show` to find podcast ids. Episodes come back as songs with `extra.type` "episode", audiobooks as collections. Results follow the country of the server's IP; `region` is accepted but does not change them.

Parameters:
- query (string; required; also keyword, q): Search terms.
- type (string; optional; one of track, album, artist, playlist, show, episode, audiobook): Kind of result.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/spotify/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=taylor swift"
```


## Apple Music

### Apple Music artist

URL: https://socialscrape.io/docs/api/apple-music/artist
Request: GET /v1/apple-music/artist
Cost: 1 credit. Status: beta.

Bio, origin, genres, top songs and albums. Apple Music shows no follower or listener counts, so `stats` is empty. `region` is the storefront (default us); a URL carries its own.

Parameters:
- url (url; optional): Apple Music artist URL.
- id (string; optional): Apple Music artist id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/apple-music/artist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://music.apple.com/us/artist/taylor-swift/159260351"
```

### Apple Music album

URL: https://socialscrape.io/docs/api/apple-music/album
Request: GET /v1/apple-music/album
Cost: 1 credit. Status: beta.

The album with its tracks, label, UPC, copyright and editorial notes.

Parameters:
- url (url; optional): Apple Music album URL.
- id (string; optional): Apple Music album id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/apple-music/album" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1468058165"
```

### Apple Music track

URL: https://socialscrape.io/docs/api/apple-music/track
Request: GET /v1/apple-music/track
Cost: 1 credit. Status: beta.

Title, artists, album, duration, ISRC, composer and the 30 second preview. A track link on an album page ends in `?i=<song id>`; that id is the song's.

Parameters:
- url (url; optional): Apple Music song URL.
- id (string; optional): Apple Music song id.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/apple-music/track" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "id=1468058169"
```

### Apple Music search

URL: https://socialscrape.io/docs/api/apple-music/search
Request: GET /v1/apple-music/search
Cost: 1 credit. Status: beta.

Public results for artists, albums, songs, playlists, stations and music videos. Without `type` every section is returned, 8 of each; with `type`, 25 of that kind. Music videos come back as songs with `extra.type` "music_video", playlists and stations as collections. `radio_episode` is not offered by Apple's public catalog search and answers invalid_params.

Parameters:
- query (string; required; also keyword, q): Search terms.
- type (string; optional; one of all, song, album, artist, playlist, station, music_video, radio_episode): Kind of result; `all` returns every section.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/apple-music/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=taylor swift"
```


## SoundCloud

### SoundCloud artist

URL: https://socialscrape.io/docs/api/soundcloud/artist
Request: GET /v1/soundcloud/artist
Cost: 1 credit. Status: beta.

Followers, track count, bio, location, avatar, banner and the social links the artist lists.

Parameters:
- url (url; optional): Artist URL (soundcloud.com/<user>).
- handle (string; optional; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/soundcloud/artist" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=flume"
```

### SoundCloud artist tracks

URL: https://socialscrape.io/docs/api/soundcloud/artist-tracks
Request: GET /v1/soundcloud/artist/tracks
Cost: 1 credit. Status: beta.

An artist's public tracks, newest first, up to 20 a page (private or blocked tracks are left out, so a page can be shorter); `parent` is the artist. Pass the cursor back until it is null.

Parameters:
- url (url; optional): Artist URL (soundcloud.com/<user>).
- handle (string; optional; also username): Username, with or without the leading @.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/soundcloud/artist/tracks" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=flume"
```

### SoundCloud track

URL: https://socialscrape.io/docs/api/soundcloud/track
Request: GET /v1/soundcloud/track
Cost: 1 credit. Status: beta.

Title, artist, duration, play, like and comment counts, genre, license, ISRC and release date.

Parameters:
- url (url; required): Track URL (soundcloud.com/<user>/<track>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/soundcloud/track" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://soundcloud.com/flume/all-of-the-worlds"
```


## GitHub

### GitHub user

URL: https://socialscrape.io/docs/api/github/user
Request: GET /v1/github/user
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds"
```

### GitHub user repositories

URL: https://socialscrape.io/docs/api/github/user-repositories
Request: GET /v1/github/user/repositories
Cost: 1 credit. Status: beta.

A user's public repositories with description, language, stars, forks, topics, license and dates, 30 a page. `type` and `direction` pass straight through to GitHub.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- type (string; optional; one of owner, all, member): Repository type.
- sort (string; optional; one of updated, created, pushed, full_name; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- direction (string; optional; one of asc, desc): Sort direction.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/repositories" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds"
```

### GitHub repository

URL: https://socialscrape.io/docs/api/github/repository
Request: GET /v1/github/repository
Cost: 1 credit. Status: beta.

Parameters:
- url (url; optional): Repository URL (github.com/<owner>/<repo>).
- repo (string; optional; also full_name): "owner/name".

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/repository" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "repo=torvalds/linux"
```

### GitHub followers

URL: https://socialscrape.io/docs/api/github/user-followers
Request: GET /v1/github/user/followers
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/followers" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds"
```

### GitHub following

URL: https://socialscrape.io/docs/api/github/user-following
Request: GET /v1/github/user/following
Cost: 1 credit. Status: beta.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/following" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=kentcdodds"
```

### GitHub contribution calendar

URL: https://socialscrape.io/docs/api/github/user-contributions
Request: GET /v1/github/user/contributions
Cost: 1 credit. Status: beta.

The public contribution graph for one year: the total and a count per day.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- year (integer; optional): Calendar year (2008 onward); default the current year.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/contributions" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds" \
  --data-urlencode "year=2025"
```

### GitHub public activity

URL: https://socialscrape.io/docs/api/github/user-activity
Request: GET /v1/github/user/activity
Cost: 1 credit. Status: beta.

The profile's contribution activity timeline (commits, repositories created, pull requests, issues, reviews), one month a page, newest month first, paging backward through the year.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- year (integer; optional): Calendar year (2008 onward); default the current year.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/activity" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=gaearon" \
  --data-urlencode "year=2025" \
  --data-urlencode "cursor=7"
```

### GitHub pull requests by a user

URL: https://socialscrape.io/docs/api/github/user-pull-requests
Request: GET /v1/github/user/pull-requests
Cost: 1 credit. Status: beta.

Public pull requests the user authored, newest first, from GitHub's public search index, which serves at most the first 1,000 results of any search.

Parameters:
- handle (string; optional; also username, login): GitHub username.
- url (url; optional): Profile URL (github.com/<user>).
- state (string; optional; one of open, closed, merged, all): PR state.
- since (string; optional): Only pull requests created on or after this date (YYYY-MM-DD).
- until (string; optional): Only pull requests created on or before this date (YYYY-MM-DD).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/user/pull-requests" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=torvalds"
```

### GitHub trending repositories

URL: https://socialscrape.io/docs/api/github/trending-repositories
Request: GET /v1/github/trending/repositories
Cost: 1 credit. Status: beta.

GitHub's public Trending page: ranked repositories with description, language, stars, forks, stars gained in the range and the users who built them.

Parameters:
- language (string; optional): Coding language, e.g. javascript, python, go.
- since (string; optional; one of daily, weekly, monthly): Trending range.
- spoken_language_code (string; optional): Spoken language filter, e.g. en.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/trending/repositories" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "language=python" \
  --data-urlencode "since=weekly"
```

### GitHub trending developers

URL: https://socialscrape.io/docs/api/github/trending-developers
Request: GET /v1/github/trending/developers
Cost: 1 credit. Status: beta.

GitHub's public Trending developers page: ranked users with name, avatar and the popular repository GitHub shows for them (in `extra`).

Parameters:
- language (string; optional): Coding language, e.g. javascript, python, go.
- since (string; optional; one of daily, weekly, monthly): Trending range.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/github/trending/developers" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "language=python" \
  --data-urlencode "since=weekly"
```


## Kwai

### Kwai profile

URL: https://socialscrape.io/docs/api/kwai/profile
Request: GET /v1/kwai/profile
Cost: 1 credit. Status: beta.

A public profile: name, bio, avatar, verification, counts of posts, likes, followers and following. Kwai's follower figure is unreliable (the official Brazil account reports 1), so treat it with care.

Parameters:
- url (url; optional): Profile URL (kwai.com/@<user>).
- handle (string; optional; also username): Username, with or without the leading @.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/kwai/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=KwaiBrasilOficial"
```

### Kwai profile posts

URL: https://socialscrape.io/docs/api/kwai/profile-posts
Request: GET /v1/kwai/profile/posts
Cost: 1 credit. Status: beta.

A user's public posts: caption, media URLs, covers, counts and author. Pass the cursor back for more.

Parameters:
- url (url; optional): Profile URL (kwai.com/@<user>).
- handle (string; optional; also username): Username, with or without the leading @.
- limit (integer; optional; also count): Number of posts per page, at most 50.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/kwai/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=KwaiBrasilOficial" \
  --data-urlencode "limit=10"
```

### Kwai post

URL: https://socialscrape.io/docs/api/kwai/post
Request: GET /v1/kwai/post
Cost: 1 credit. Status: beta.

Parameters:
- url (url; required): Post URL (kwai.com/@<user>/video/<id>; the /photo/<id> form works too).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/kwai/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.kwai.com/@KwaiBrasilOficial/video/5193363430624671876"
```


## Rumble

### Rumble video details

URL: https://socialscrape.io/docs/api/rumble/video
Request: GET /v1/rumble/video
Cost: 1 credit. Status: beta.

One video by link: title, description, channel, views, likes, comment count, duration, publish time, thumbnail, media URLs and caption languages. Embed links (rumble.com/embed/v...) work too.

Parameters:
- url (url; required): Video URL (rumble.com/v...-title.html).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/rumble/video" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
```

### Rumble channel videos

URL: https://socialscrape.io/docs/api/rumble/channel-videos
Request: GET /v1/rumble/channel/videos
Cost: 1 credit. Status: beta.

A channel's videos (shorts are marked `type: short`) with the channel details in `parent`. Pass the cursor back for the next page of about 25.

Parameters:
- handle (string; optional; also username): Channel handle (the part after rumble.com/c/).
- url (url; optional): Channel URL (rumble.com/c/<handle> or rumble.com/user/<handle>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/rumble/channel/videos" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=CuteCats223"
```

### Rumble search

URL: https://socialscrape.io/docs/api/rumble/search
Request: GET /v1/rumble/search
Cost: 1 credit. Status: beta.

Search Rumble videos. Each result has the title, channel, views, likes, duration, publish time and thumbnail; pass the cursor back for the next page of about 25.

Parameters:
- query (string; required; also keyword, q): Search terms.
- sort (string; optional; one of relevance, views, latest; also sort_by, sortBy, order): Order of results. Changing it restarts the cursor chain.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/rumble/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=funny cats"
```

### Rumble video comments

URL: https://socialscrape.io/docs/api/rumble/video-comments
Request: GET /v1/rumble/video/comments
Cost: 1 credit. Status: beta.

The comments on a video in one page, in Rumble's own order, with likes, dislikes and reply counts. Replies come after the comment they answer, with `parent_id` set. Videos whose comments Rumble shows only to signed-in users answer `private`. `parent` is the video.

Parameters:
- url (url; required): Video URL (rumble.com/v...-title.html).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/rumble/video/comments" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
```

### Rumble video transcript

URL: https://socialscrape.io/docs/api/rumble/video-transcript
Request: GET /v1/rumble/video/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Captions when Rumble has them (its own auto captions count as captions); AI transcription of the audio when it does not.

Parameters:
- url (url; required): Video URL (rumble.com/v...-title.html).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/rumble/video/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html"
```


## Telegram

### Telegram public channel

URL: https://socialscrape.io/docs/api/telegram/channel
Request: GET /v1/telegram/channel
Cost: 1 credit. Status: beta.

Name, description, avatar, verification, member count and media counters of a public channel or group, read from Telegram's public web preview (no Telegram account). Private and invite-only chats are not supported.

Parameters:
- handle (string; optional; also username): Channel username, without @.
- url (url; optional): Channel URL (t.me/<name>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/telegram/channel" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=durov"
```

### Telegram public channel posts

URL: https://socialscrape.io/docs/api/telegram/channel-posts
Request: GET /v1/telegram/channel/posts
Cost: 1 credit. Status: beta.

One web-preview page of posts: text, date, views, reactions, forwards and media previews. The cursor (a post number) fetches the previous page.

Parameters:
- handle (string; optional; also username): Channel username, without @.
- url (url; optional): Channel URL (t.me/<name>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/telegram/channel/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=durov"
```

### Telegram public post

URL: https://socialscrape.io/docs/api/telegram/post
Request: GET /v1/telegram/post
Cost: 1 credit. Status: beta.

One public post by URL: text, date, views, reactions, forward source, media and link previews.

Parameters:
- url (url; required): Post URL (t.me/<channel>/<number>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/telegram/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://t.me/durov/543"
```


## Cosmos

### Cosmos profile

URL: https://socialscrape.io/docs/api/cosmos/profile
Request: GET /v1/cosmos/profile
Cost: 1 credit. Status: beta.

A public Cosmos profile: bio, links and follower counts.

Parameters:
- handle (string; required; also username): Cosmos username, without a profile URL.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/profile" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=design"
```

### Cosmos profile posts

URL: https://socialscrape.io/docs/api/cosmos/profile-posts
Request: GET /v1/cosmos/profile/posts
Cost: 1 credit. Status: beta.

The public posts saved to a profile. Keep the cursor unchanged and stop when `has_more` is false.

Parameters:
- handle (string; required; also username): Cosmos username, without a profile URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/profile/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=design"
```

### Cosmos profile collections

URL: https://socialscrape.io/docs/api/cosmos/profile-collections
Request: GET /v1/cosmos/profile/collections
Cost: 1 credit. Status: beta.

The public collections a user owns. Keep the cursor unchanged and stop when `has_more` is false.

Parameters:
- handle (string; required; also username): Cosmos username, without a profile URL.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/profile/collections" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "handle=design"
```

### Cosmos post

URL: https://socialscrape.io/docs/api/cosmos/post
Request: GET /v1/cosmos/post
Cost: 1 credit. Status: beta.

A public Cosmos post: media URLs, captions, source links and the save count.

Parameters:
- url (url; required): Public post URL (cosmos.so/e/<id>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/post" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.cosmos.so/e/2107587668"
```

### Cosmos collection

URL: https://socialscrape.io/docs/api/cosmos/collection
Request: GET /v1/cosmos/collection
Cost: 1 credit. Status: beta.

A public collection: owner, description, cover, counts and its public subcollections (in `extra`).

Parameters:
- url (url; required): Public collection URL (cosmos.so/<user>/<collection>).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/collection" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.cosmos.so/design/the-best-band-posters"
```

### Cosmos collection posts

URL: https://socialscrape.io/docs/api/cosmos/collection-posts
Request: GET /v1/cosmos/collection/posts
Cost: 1 credit. Status: beta.

Public posts saved to a collection; `parent` is the collection.

Parameters:
- url (url; required): Public collection URL (cosmos.so/<user>/<collection>).
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/collection/posts" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.cosmos.so/design/the-best-band-posters"
```

### Cosmos search

URL: https://socialscrape.io/docs/api/cosmos/search
Request: GET /v1/cosmos/search
Cost: 1 credit. Status: beta.

Search public Cosmos posts by keyword. Cosmos may return related posts without an exact match.

Parameters:
- query (string; required; also keyword, q): Search terms.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl -G "https://api.socialscrape.io/v1/cosmos/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "query=architecture"
```


## Transcript from any URL

### Transcript from any video URL

URL: https://socialscrape.io/docs/api/transcript/from-url
Request: GET /v1/transcript
Cost: 1 credit for captions; AI transcription 1 up to 2 minutes, then 1 per started minute. Status: beta.

Detects the platform from the URL and runs its transcript endpoint: YouTube, TikTok, Instagram, X, Facebook, LinkedIn, Reddit, Twitch clips, Kick clips and Rumble. Same price, same cache.

Parameters:
- url (url; required): Video URL on any supported platform.
- language (string; optional; also lang): Preferred caption language (BCP 47).

Example:

```bash
curl -G "https://api.socialscrape.io/v1/transcript" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  --data-urlencode "url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```


## Account

### Credit balance

URL: https://socialscrape.io/docs/api/account/credits
Request: GET /v1/account/credits
Cost: Free. Status: beta.

The credits left for the team behind the key. Free.

Example:

```bash
curl "https://api.socialscrape.io/v1/account/credits" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Request history

URL: https://socialscrape.io/docs/api/account/usage
Request: GET /v1/account/usage
Cost: Free. Status: beta.

The team's past API requests, newest first: endpoint, status, credits charged and time. Free. The cursor is the page number (at most 100 pages).

Parameters:
- endpoint (string; optional): Only requests whose path contains this text, "/v1/tiktok/profile".
- status (integer; optional; also statusCode, status_code): Only requests that answered this HTTP status.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/account/usage" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Daily usage

URL: https://socialscrape.io/docs/api/account/usage-daily
Request: GET /v1/account/usage/daily
Cost: Free. Status: beta.

Requests and credits charged per day for the last 30 days. Free.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/account/usage/daily" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Most used endpoints

URL: https://socialscrape.io/docs/api/account/usage-routes
Request: GET /v1/account/usage/routes
Cost: Free. Status: beta.

The team's 20 most called endpoints with requests and credits charged each. Defaults to the last 24 hours; custom ranges up to one year. Free.

Parameters:
- start_time (string; optional; also startTime): Start of the range, ISO 8601.
- end_time (string; optional; also endTime): End of the range, ISO 8601.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/account/usage/routes" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```


## Jobs

### Job result

URL: https://socialscrape.io/docs/api/jobs/get
Request: GET /v1/jobs/{job_id}
Cost: Free. Status: beta.

Poll a job that answered 202. Free while pending; when done this returns the job's final envelope (and charges then, once).

Parameters:
- job_id (string; required): Job id from the 202 answer.

Example:

```bash
curl "https://api.socialscrape.io/v1/jobs/job_0123456789abcdef01234567" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```


## Batch

### Batch requests

URL: https://socialscrape.io/docs/api/batch/create
Request: POST /v1/batch
Cost: The sum of each sub-request's charge. Status: beta.

Up to 100 GET requests in one call; each result is a full envelope, charged as if called alone (cached repeats and failures free). Items run concurrently, each counts toward the rate limit, and a failed item never fails the others. Send an Idempotency-Key header to retry a batch safely: the first answer is replayed and nothing is charged twice.

Parameters:
- requests (array; required): List of {"path": "/v1/...", "params": {...}}.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/batch" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"requests":[{"path":"/v1/github/user","params":{"handle":"torvalds"}},{"path":"/v1/github/user","params":{"handle":"gaearon"}}]}'
```


## Monitors

### Create a monitor

URL: https://socialscrape.io/docs/api/monitors/create
Request: POST /v1/monitors
Cost: Free. Status: beta.

Watch a list endpoint (a profile's posts, a search) and receive new items at a webhook.

Parameters:
- endpoint (string; required): Path of a list endpoint, "/v1/tiktok/profile/videos".
- params (object; required): That endpoint's params.
- interval_minutes (integer; optional): How often to check.
- webhook_url (string; required): HTTPS URL that receives events.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/monitors" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"endpoint":"/v1/github/user/repositories","params":{"handle":"torvalds"},"interval_minutes":60,"webhook_url":"https://example.com/hook"}'
```

### List monitors

URL: https://socialscrape.io/docs/api/monitors/list
Request: GET /v1/monitors
Cost: Free. Status: beta.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/monitors" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Delete a monitor

URL: https://socialscrape.io/docs/api/monitors/delete
Request: DELETE /v1/monitors/{monitor_id}
Cost: Free. Status: beta.

Parameters:
- monitor_id (string; required): Monitor id.

Example:

```bash
curl -X DELETE "https://api.socialscrape.io/v1/monitors/mon_0123456789abcdef" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Send a test event

URL: https://socialscrape.io/docs/api/monitors/test
Request: POST /v1/monitors/{monitor_id}/test
Cost: Free. Status: beta.

Send a signed test event ("type": "test") to the monitor's webhook now and report what the receiver answered. Free; nothing is stored.

Parameters:
- monitor_id (string; required): Monitor id.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/monitors/mon_0123456789abcdef/test" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Webhook delivery log

URL: https://socialscrape.io/docs/api/monitors/deliveries
Request: GET /v1/monitors/{monitor_id}/deliveries
Cost: Free. Status: beta.

Every delivery attempt of the monitor's events, newest first: status code, error, and whether the chain gave up (dead letter). Free.

Parameters:
- monitor_id (string; required): Monitor id.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/monitors/mon_0123456789abcdef/deliveries" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Send an event again

URL: https://socialscrape.io/docs/api/monitors/redeliver
Request: POST /v1/monitors/events/{event_id}/redeliver
Cost: Free. Status: beta.

Queue an event that was not delivered (a dead letter, usually) for a fresh chain of attempts. An event already delivered is refused. Free.

Parameters:
- event_id (string; required): Event id.

Example:

```bash
curl -X POST "https://api.socialscrape.io/v1/monitors/events/evt_0123456789abcdef/redeliver" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```

### Monitor events

URL: https://socialscrape.io/docs/api/monitors/events
Request: GET /v1/monitors/events
Cost: Free. Status: beta.

Events from the team's monitors, newest first (the same events the webhooks deliver).

Parameters:
- monitor_id (string; optional): Only this monitor's events.
- cursor (string, optional): from the previous page; the list ends when has_more is false.

Example:

```bash
curl "https://api.socialscrape.io/v1/monitors/events" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY"
```