# SocialCrawl API — Full Reference

## Base URL: https://www.socialcrawl.dev/v1

## Authentication

Every request requires an `x-api-key` header:

```
curl https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \
  -H "x-api-key: sc_your_api_key_here"
```

## Response Format

All responses follow this envelope:

```json
{
  "success": true,
  "platform": "tiktok",
  "endpoint": "/v1/tiktok/profile",
  "data": { ... },
  "credits_used": 1,
  "credits_remaining": 4999,
  "request_id": "req-XXXXX",
  "cached": false
}
```

---

## Account — Meta Endpoints

Account metadata (balance, usage). These endpoints cost 0 credits and never touch upstream platforms.

### GET /credits/balance

Check your current credit balance and recent deduction count.

Credit cost: 0 (metadata call)

Response:

```json
{
  "success": true,
  "platform": "meta",
  "endpoint": "/v1/credits/balance",
  "data": {
    "balance": 4999,
    "recent_deductions": 12
  },
  "credits_used": 0,
  "credits_remaining": 4999,
  "request_id": "req-XXXXX",
  "cached": false
}
```

```
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Amazon

### GET /amazon/shop

Get Amazon shop page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Amazon shop or storefront page

```
curl "https://www.socialcrawl.dev/v1/amazon/shop?url=https://www.amazon.com/shop/influencer123" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Facebook

### GET /facebook/profile

Get Facebook page profile

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Facebook page or profile
- get_business_hours (optional, string) — Get the business's hours

```
curl "https://www.socialcrawl.dev/v1/facebook/profile?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/profile/posts

List Facebook page posts (oneOf: url|pageId)

Credit cost: 1 (standard)

Parameters:
- url (optional, string) — Full URL of the Facebook page or profile to fetch posts for
- pageId (optional, string) — Facebook profile page id
- cursor (optional, string) — To paginate through the posts
- Constraint: one of url, pageId (at least one required)

```
curl "https://www.socialcrawl.dev/v1/facebook/profile/posts?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/post

Get Facebook post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Facebook post
- get_comments (optional, boolean) — Whether you want to get the first several comments of the post
- get_transcript (optional, boolean) — Whether you want to get the transcript of the post

```
curl "https://www.socialcrawl.dev/v1/facebook/post?url=https://www.facebook.com/Meta/posts/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/post/comments

List Facebook post comments (oneOf: url|feedback_id)

Credit cost: 1 (standard)

Parameters:
- url (optional, string) — Full URL of the Facebook post to fetch comments for
- feedback_id (optional, string) — Using feedback_id (instead of url) will *really* speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post.
- cursor (optional, string) — Cursor to get more comments. Get 'cursor' from previous response.
- Constraint: one of url, feedback_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/facebook/post/comments?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/group/posts

List Facebook group posts (oneOf: url|group_id)

Credit cost: 1 (standard)

Parameters:
- url (optional, string) — Full URL of the Facebook group
- group_id (optional, string) — The ID of the group
- sort_by (optional, enum: TOP_POSTS | RECENT_ACTIVITY | CHRONOLOGICAL | CHRONOLOGICAL_LISTINGS) — How to sort the posts
- cursor (optional, string) — The cursor to paginate to the next page
- Constraint: one of url, group_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/facebook/group/posts?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/post/transcript

Get Facebook video transcript

Credit cost: 10 (premium)

Parameters:
- url (required) — Full URL of the Facebook video post

```
curl "https://www.socialcrawl.dev/v1/facebook/post/transcript?url=https://www.facebook.com/Meta/videos/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/profile/photos

List Facebook profile photos

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Facebook page or profile
- next_page_id (optional, string) — To paginate through to the next page
- cursor (optional, string) — To paginate through to the next page

```
curl "https://www.socialcrawl.dev/v1/facebook/profile/photos?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/profile/reels

List Facebook profile reels

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Facebook page or profile
- next_page_id (optional, string) — To paginate through to the next page
- cursor (optional, string) — To paginate through to the next page

```
curl "https://www.socialcrawl.dev/v1/facebook/profile/reels?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/adlibrary/ad

Get Facebook Ad Library ad details (oneOf: id|url)

Credit cost: 5 (advanced)

Parameters:
- id (optional, string) — Facebook Ad Library ad ID
- url (optional, string) — Facebook Ad URL
- get_transcript (optional, boolean) — Get the transcript of the ad. Only works if the video is under 2 minutes.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of id, url (at least one required)

```
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/adlibrary/company/ads

List Facebook Ad Library company ads (oneOf: pageId|companyName)

Credit cost: 5 (advanced)

Parameters:
- pageId (optional, string) — Facebook page ID of the advertiser
- companyName (optional, string) — The name of the company. Can either use this or pageId
- country (optional, string) — This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
- status (optional, enum: ALL | ACTIVE | INACTIVE) — Status of the ad. Defaults to ACTIVE.
- media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE) — Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme.
- language (optional, string) — Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc
- sort_by (optional, enum: total_impressions | relevancy_monthly_grouped) — Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
- start_date (optional, string) — Start date to search for. Format: YYYY-MM-DD
- end_date (optional, string) — End date to search for. Format: YYYY-MM-DD
- cursor (optional, string) — Cursor to paginate through results
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of pageId, companyName (at least one required)

```
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/company/ads?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/adlibrary/search/ads

Search Facebook Ad Library

Credit cost: 5 (advanced)

Parameters:
- query (required) — Search keyword or phrase to find ads in the Facebook Ad Library
- sort_by (optional, enum: total_impressions | relevancy_monthly_grouped) — Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions.
- search_type (optional, enum: keyword_unordered | keyword_exact_phrase) — If you want to search by exact phrase or not
- ad_type (optional, enum: all | political_and_issue_ads) — Search for all ads or only political and issue ads
- country (optional, string) — This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL.
- status (optional, enum: ALL | ACTIVE | INACTIVE) — Status of the ad. Defaults to ACTIVE.
- media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE) — Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme.
- start_date (optional, string) — Impressions start date. Needs to be in YYYY-MM-DD format.
- end_date (optional, string) — Impressions end date. Needs to be in YYYY-MM-DD format.
- cursor (optional, string) — Cursor to paginate through results
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads?query=artificial intelligence" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /facebook/adlibrary/search/companies

Search Facebook Ad Library companies

Credit cost: 5 (advanced)

Parameters:
- query (required) — Search keyword or phrase to find companies in the Facebook Ad Library

```
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/companies?query=Nike" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Github

### GET /github/profile

Get a GitHub user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — GitHub username — 1–39 chars, alphanumeric + non-consecutive hyphens, no leading/trailing hyphen.

```
curl "https://www.socialcrawl.dev/v1/github/profile?handle=octocat" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo

Get a GitHub repository

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.

```
curl "https://www.socialcrawl.dev/v1/github/repo?url=https://github.com/octocat/Hello-World" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/profile/repos

List a GitHub user's repositories

Credit cost: 1 (standard)

Parameters:
- handle (required) — GitHub username.
- type (optional, enum: all | owner | member) — Filter — `all`, `owner`, or `member`. Defaults to `owner`.
- sort (optional, enum: created | updated | pushed | full_name) — Sort field — `created`, `updated`, `pushed`, or `full_name`. Defaults to `full_name`.
- direction (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `asc` for full_name, `desc` otherwise.
- per_page (optional, integer) — Repos per page (1–100). Defaults to 30.
- page (optional, integer) — 1-indexed page number for pagination.

```
curl "https://www.socialcrawl.dev/v1/github/profile/repos?handle=octocat" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo/readme

Get a repository's README

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.

```
curl "https://www.socialcrawl.dev/v1/github/repo/readme?url=https://github.com/octocat/Hello-World" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo/releases

List a repository's releases

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.
- per_page (optional, integer) — Releases per page (1–100). Defaults to 30.
- page (optional, integer) — 1-indexed page number.

```
curl "https://www.socialcrawl.dev/v1/github/repo/releases?url=https://github.com/facebook/react" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo/issues

List a repository's issues (and PRs)

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.
- state (optional, enum: open | closed | all) — `open`, `closed`, or `all`. Defaults to `open`.
- labels (optional, string) — Comma-separated label names (e.g. `bug,help wanted`).
- sort (optional, enum: created | updated | comments) — `created`, `updated`, or `comments`. Defaults to `created`.
- direction (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `desc`.
- since (optional, string) — Only issues updated at or after this ISO 8601 timestamp.
- per_page (optional, integer) — Issues per page (1–100). Defaults to 30.
- page (optional, integer) — 1-indexed page number.

```
curl "https://www.socialcrawl.dev/v1/github/repo/issues?url=https://github.com/facebook/react" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/issue

Get a single issue or pull request

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub HTML URL — `https://github.com/{owner}/{repo}/issues/{n}` or `/pull/{n}`.

```
curl "https://www.socialcrawl.dev/v1/github/issue?url=https://github.com/facebook/react/issues/27522" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/issue/comments

Get comments on an issue or pull request

Credit cost: 1 (standard)

Parameters:
- url (required) — GitHub HTML URL of the issue or PR.
- sort (optional, enum: created | updated) — `created` or `updated`. Defaults to `created`.
- direction (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `asc`.
- since (optional, string) — Only comments updated at or after this ISO 8601 timestamp.
- per_page (optional, integer) — Comments per page (1–100). Defaults to 30.
- page (optional, integer) — 1-indexed page number.

```
curl "https://www.socialcrawl.dev/v1/github/issue/comments?url=https://github.com/facebook/react/issues/27522" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/search

Search GitHub issues and pull requests

Credit cost: 1 (standard)

Parameters:
- query (required) — GitHub search query (uses GitHub's qualifier syntax — see https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests).
- sort (optional, enum: reactions | comments | created | updated) — Sort field — `reactions`, `comments`, `created`, `updated`. Defaults to best-match relevance.
- order (optional, enum: asc | desc) — `asc` or `desc`. Defaults to `desc`.
- per_page (optional, integer) — Results per page (1–100). Defaults to 30.
- page (optional, integer) — 1-indexed page number.

```
curl "https://www.socialcrawl.dev/v1/github/search?query=repo:vercel/next.js is:issue is:open" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo/top-issues

Top feature request and top complaint for a repository

Credit cost: 5 (advanced)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.

```
curl "https://www.socialcrawl.dev/v1/github/repo/top-issues?url=https://github.com/facebook/react" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/repo/dossier

Full project dossier for a repository

Credit cost: 5 (advanced)

Parameters:
- url (required) — GitHub repo URL — `https://github.com/{owner}/{repo}`.

```
curl "https://www.socialcrawl.dev/v1/github/repo/dossier?url=https://github.com/facebook/react" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /github/user/profile-velocity

User contribution velocity dossier

Credit cost: 10 (premium)

Parameters:
- handle (required) — GitHub username.
- depth (optional, enum: quick | default | deep) — `quick`, `default`, or `deep`. Defaults to `default`. Trades off upstream calls vs. dossier richness.

```
curl "https://www.socialcrawl.dev/v1/github/user/profile-velocity?handle=octocat" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Google

### GET /google/search

Google web search

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase
- region (optional, string) — 2 letter country code, ie US, UK, CA, etc This will show results from that country
- date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted
- page (optional, integer) — Page number to retrieve

```
curl "https://www.socialcrawl.dev/v1/google/search?query=best restaurants in London" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /google/ad

Get Google ad details

Credit cost: 5 (advanced)

Parameters:
- url (required) — Full URL of the Google ad or Ads Transparency Center page

```
curl "https://www.socialcrawl.dev/v1/google/ad?url=https://adstransparency.google.com/advertiser/AR12345678901234567" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /google/adlibrary/advertisers/search

Search Google Ad Library advertisers

Credit cost: 5 (advanced)

Parameters:
- query (required) — Search keyword or phrase to find advertisers in the Google Ads Transparency Center

```
curl "https://www.socialcrawl.dev/v1/google/adlibrary/advertisers/search?query=Nike" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /google/company/ads

List Google ads by company (oneOf: domain|advertiser_id)

Credit cost: 5 (advanced)

Parameters:
- domain (optional, string) — Company domain name to look up ads for
- advertiser_id (optional, string) — The advertiser id of the company
- topic (optional, enum: all | political) — The topic to search for. If you search for 'political', you will also need to pass a 'region', like 'US' or 'AU'
- region (optional, string) — The region to search for. Defaults to anywhere
- start_date (optional, string) — Start date to search for. Format: YYYY-MM-DD
- end_date (optional, string) — End date to search for. Format: YYYY-MM-DD
- get_ad_details (optional, string) — Set to true to get the ad details. Will cost 25 credits.
- cursor (optional, string) — Cursor to paginate through results
- Constraint: one of domain, advertiser_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/google/company/ads?" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Hackernews

### GET /hackernews/search

Search Hacker News

Credit cost: 1 (standard)

Parameters:
- query (required) — Free-text search term.
- tags (optional, string) — Algolia tag filter — comma-separated. Common values: "story", "comment", "poll", "show_hn", "ask_hn", "front_page", "author_<username>". Defaults to "story".
- numericFilters (optional, string) — Algolia numeric filter expression — e.g. "created_at_i>1700000000,points>10". Combine with commas for AND. Overrides the default "points>2" floor when provided.
- hitsPerPage (optional, integer) — Hits per page (1–1000). Defaults to 30.
- page (optional, integer) — 0-indexed page number for pagination.

```
curl "https://www.socialcrawl.dev/v1/hackernews/search?query=claude code" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /hackernews/story

Get a Hacker News story

Credit cost: 1 (standard)

Parameters:
- id (required) — HN story id (the numeric `objectID`).

```
curl "https://www.socialcrawl.dev/v1/hackernews/story?id=8863" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /hackernews/story/comments

Get comments on a Hacker News story

Credit cost: 1 (standard)

Parameters:
- id (required) — HN story id (the numeric `objectID`).

```
curl "https://www.socialcrawl.dev/v1/hackernews/story/comments?id=8863" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /hackernews/profile

Get a Hacker News user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Hacker News username (case-sensitive, e.g. `pg` or `kogir`).

```
curl "https://www.socialcrawl.dev/v1/hackernews/profile?handle=pg" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Instagram

### GET /instagram/profile

Get Instagram user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Instagram username without the @ symbol
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/instagram/profile?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/profile/posts

List Instagram user posts

Credit cost: 1 (standard)

Parameters:
- handle (required) — Instagram username without the @ symbol
- next_max_id (optional, string) — Cursor to get next page of results.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/instagram/profile/posts?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/post

Get Instagram post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Instagram post
- region (optional, string) — 2 letter country code to set the proxy in
- trim (optional, boolean) — Set to true to get a trimmed response
- download_media (optional, boolean) — Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.

```
curl "https://www.socialcrawl.dev/v1/instagram/post?url=https://www.instagram.com/p/CwA1234abcd/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/post/comments

List Instagram post comments

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Instagram post to fetch comments for
- cursor (optional, string) — The cursor to get more comments. Get 'cursor' from previous response.

```
curl "https://www.socialcrawl.dev/v1/instagram/post/comments?url=https://www.instagram.com/p/CwA1234abcd/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/basic-profile

Get Instagram basic profile

Credit cost: 1 (standard)

Parameters:
- userId (optional, string) — Instagram numeric user ID

```
curl "https://www.socialcrawl.dev/v1/instagram/basic-profile?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/profile/reels

List Instagram user reels (oneOf: user_id|handle)

Credit cost: 1 (standard)

Parameters:
- user_id (optional, string) — Instagram user id. Use this for faster response times.
- handle (optional, string) — Instagram username without the @ symbol
- max_id (optional, string) — Max id to get more reels. Get 'max_id' from previous response.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of user_id, handle (at least one required)

```
curl "https://www.socialcrawl.dev/v1/instagram/profile/reels?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/highlights

List Instagram story highlights (oneOf: user_id|handle)

Credit cost: 1 (standard)

Parameters:
- user_id (optional, string) — Instagram user id. Use for faster response times.
- handle (optional, string) — Instagram username without the @ symbol
- Constraint: one of user_id, handle (at least one required)

```
curl "https://www.socialcrawl.dev/v1/instagram/highlights?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/highlight/detail

Get Instagram highlight detail

Credit cost: 1 (standard)

Parameters:
- id (optional, string) — Instagram highlight ID

```
curl "https://www.socialcrawl.dev/v1/instagram/highlight/detail?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/search/reels

Search Instagram reels

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find Instagram reels
- date_posted (optional, enum: last-hour | last-day | last-week | last-month | last-year) — Date posted
- page (optional, integer) — The page number to return.

```
curl "https://www.socialcrawl.dev/v1/instagram/search/reels?query=workout routine" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/media/transcript

Get Instagram media transcript

Credit cost: 10 (premium)

Parameters:
- url (required) — Full URL of the Instagram video or reel

```
curl "https://www.socialcrawl.dev/v1/instagram/media/transcript?url=https://www.instagram.com/reel/CwA1234abcd/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/user/embed

Get Instagram user embed HTML

Credit cost: 1 (standard)

Parameters:
- handle (required) — Instagram username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/instagram/user/embed?handle=instagram" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /instagram/song/reels

List Instagram reels using a song

Credit cost: 1 (standard)

Parameters:
- audio_id (required) — Instagram audio/song ID
- max_id (optional, string) — How you paginate the results. Pass the max_id from the previous response to get the next set of reels.

```
curl "https://www.socialcrawl.dev/v1/instagram/song/reels?audio_id=243313786724210" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Kick

### GET /kick/clip

Get Kick clip details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Kick clip

```
curl "https://www.socialcrawl.dev/v1/kick/clip?url=https://kick.com/xqc/clips/clip_abc123" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Komi

### GET /komi/page

Get Komi page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Komi page

```
curl "https://www.socialcrawl.dev/v1/komi/page?url=https://komi.io/example" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Linkbio

### GET /linkbio/page

Get Linkbio page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Linkbio page

```
curl "https://www.socialcrawl.dev/v1/linkbio/page?url=https://lnk.bio/example" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Linkedin

### GET /linkedin/profile

Get LinkedIn user profile

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the LinkedIn profile page

```
curl "https://www.socialcrawl.dev/v1/linkedin/profile?url=https://www.linkedin.com/in/williamhgates/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /linkedin/company

Get LinkedIn company page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the LinkedIn company page

```
curl "https://www.socialcrawl.dev/v1/linkedin/company?url=https://www.linkedin.com/company/microsoft/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /linkedin/post

Get LinkedIn post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the LinkedIn post

```
curl "https://www.socialcrawl.dev/v1/linkedin/post?url=https://www.linkedin.com/posts/williamhgates_example-activity-1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /linkedin/company/posts

List LinkedIn company posts

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the LinkedIn company page
- page (optional, integer) — The page number to get

```
curl "https://www.socialcrawl.dev/v1/linkedin/company/posts?url=https://www.linkedin.com/company/microsoft/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /linkedin/ad

Get LinkedIn ad details

Credit cost: 5 (advanced)

Parameters:
- url (required) — Full URL of the LinkedIn ad

```
curl "https://www.socialcrawl.dev/v1/linkedin/ad?url=https://www.linkedin.com/ad/library/detail/12345" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /linkedin/ads/search

Search LinkedIn ads

Credit cost: 5 (advanced)

Parameters:
- company (optional, string) — The company name to search for. 'Microsoft' for example
- keyword (optional, string) — The keyword to search for
- companyId (optional, string) — The company id to search for
- countries (optional, string) — Comma separated list of countries. Example: US,CA,MX
- startDate (optional, string) — Start date to search for. Format: YYYY-MM-DD
- endDate (optional, string) — End date to search for. Format: YYYY-MM-DD
- paginationToken (optional, string) — Pagination token to paginate through results

```
curl "https://www.socialcrawl.dev/v1/linkedin/ads/search?" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Linkme

### GET /linkme/page

Get Linkme profile

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Linkme page

```
curl "https://www.socialcrawl.dev/v1/linkme/page?url=https://link.me/example" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Linktree

### GET /linktree/page

Get Linktree page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Linktree page

```
curl "https://www.socialcrawl.dev/v1/linktree/page?url=https://linktr.ee/charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Perplexity

### GET /perplexity/research

Web research via Perplexity Sonar

Credit cost: 1 (standard)

Parameters:
- query (required) — Natural-language research prompt. Sonar autonomously searches the live web and grounds the response in real sources. No prompt-engineering required — phrase it as you would to a search engine or research assistant.

```
curl "https://www.socialcrawl.dev/v1/perplexity/research?query=What is the capital of France?" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Pillar

### GET /pillar/page

Get Pillar page

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Pillar page

```
curl "https://www.socialcrawl.dev/v1/pillar/page?url=https://pillar.io/example" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Pinterest

### GET /pinterest/search

Search Pinterest pins

Credit cost: 1 (standard)

Parameters:
- query (required) — Search query
- cursor (optional, string) — Cursor
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/pinterest/search?query=home decor ideas" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /pinterest/pin

Get Pinterest pin details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Pinterest pin
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/pinterest/pin?url=https://www.pinterest.com/pin/1234567890/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /pinterest/board

Get Pinterest board

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Pinterest board
- cursor (optional, string) — The cursor to get the next page of results
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/pinterest/board?url=https://www.pinterest.com/pinterest/official-pinterest-pins/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /pinterest/user/boards

List Pinterest user boards

Credit cost: 1 (standard)

Parameters:
- handle (required) — The username of the user to get boards for. (e.g. broadstbullycom from https://www.pinterest.com/broadstbullycom/)
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/pinterest/user/boards?handle=pinterest" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Polymarket

### GET /polymarket/search

Search Polymarket prediction markets

Credit cost: 1 (standard)

Parameters:
- query (required) — Free-text search term — keywords, entity names, or topics

```
curl "https://www.socialcrawl.dev/v1/polymarket/search?query=trump 2028" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /polymarket/research

Polymarket prediction markets — multi-query research

Credit cost: 5 (advanced)

Parameters:
- query (required) — The research topic — free-text natural language (e.g. 'last 30 days bitcoin halving', 'kanye west tour'). Framing prefixes like 'last N days' and 'what are people saying about' are stripped automatically before expansion.

```
curl "https://www.socialcrawl.dev/v1/polymarket/research?query=trump 2028 election" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Reddit

### GET /reddit/subreddit

List Reddit subreddit posts

Credit cost: 1 (standard)

Parameters:
- subreddit (required) — Subreddit name without the r/ prefix
- timeframe (optional, enum: all | day | week | month | year) — Timeframe to get posts from
- sort (optional, enum: best | hot | new | top | rising) — Sort order
- after (optional, string) — After to get more posts. Get 'after' from previous response.
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/reddit/subreddit?subreddit=technology" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/subreddit/details

Get Reddit subreddit details (oneOf: subreddit|url)

Credit cost: 1 (standard)

Parameters:
- subreddit (optional, string) — Subreddit name without the r/ prefix
- url (optional, string) — Subreddit URL
- Constraint: one of subreddit, url (at least one required)

```
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/details?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/search

Search Reddit posts

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find Reddit posts
- sort (optional, enum: relevance | new | top | comment_count) — Sort by
- timeframe (optional, enum: all | day | week | month | year) — Timeframe
- after (optional, string) — Used to paginate to next page
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/reddit/search?query=best programming languages 2024" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/post/comments

List Reddit post comments

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Reddit post to fetch comments for
- cursor (optional, string) — Cursor to get more comments, or replies.
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/reddit/post/comments?url=https://www.reddit.com/r/technology/comments/abc123/example_post/" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/ad

Get Reddit ad details

Credit cost: 5 (advanced)

Parameters:
- id (required) — Reddit ad ID

```
curl "https://www.socialcrawl.dev/v1/reddit/ad?id=t3_abc123" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/ads/search

Search Reddit ads

Credit cost: 5 (advanced)

Parameters:
- query (required) — Search query
- industries (optional, enum: RETAIL_AND_ECOMMERCE | TECH_B2B | TECH_B2C | EDUCATION | ENTERTAINMENT | GAMING | FINANCIAL_SERVICES | HEALTH_AND_BEAUTY | CONSUMER_PACKAGED_GOODS | EMPLOYMENT | AUTO | TRAVEL | REAL_ESTATE | GAMBLING_AND_FANTASY_SPORTS | POLITICS_AND_GOVERNMENT | OTHER) — Industries to filter by
- budgets (optional, enum: LOW | MEDIUM | HIGH) — Budgets to filter by
- formats (optional, enum: IMAGE | VIDEO | CAROUSEL | FREE_FORM) — Formats to filter by
- placements (optional, enum: FEED | COMMENTS_PAGE) — Placements to filter by
- objectives (optional, enum: IMPRESSIONS | CLICKS | CONVERSIONS | VIDEO_VIEWABLE_IMPRESSIONS | APP_INSTALLS) — Objectives to filter by

```
curl "https://www.socialcrawl.dev/v1/reddit/ads/search?query=gaming" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /reddit/subreddit/search

Search within a subreddit

Credit cost: 1 (standard)

Parameters:
- subreddit (required) — Subreddit name (e.g. 'Fitness', not 'r/Fitness' or a full URL)
- query (optional, string) — Search query to find matching content
- sort (optional, enum: relevance | hot | top | new | comments) — Sort order. For posts/media: relevance, hot, top, new, comments. For comments: relevance, top, new
- timeframe (optional, enum: all | year | month | week | day | hour) — Timeframe to filter results
- cursor (optional, string) — Cursor to get more results. Get 'cursor' from previous response.

```
curl "https://www.socialcrawl.dev/v1/reddit/subreddit/search?subreddit=technology" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Search

### GET /search/everywhere

Universal social search across 12 platforms

Credit cost: 20 (override; tier standard)

Parameters:
- query (required) — Search query (1–512 chars)
- lookback_days (optional, integer) — Days to look back (1–365+, default 30); mutually exclusive with from_date/to_date.
- from_date (optional, string) — ISO YYYY-MM-DD lower bound; mutually exclusive with lookback_days.
- to_date (optional, string) — ISO YYYY-MM-DD upper bound; defaults to today when from_date is set alone.
- sources (optional, string) — Optional CSV allowlist of source names (mutually exclusive with exclude).
- exclude (optional, string) — Optional CSV blocklist of source names (mutually exclusive with sources).

```
curl "https://www.socialcrawl.dev/v1/search/everywhere?query=kanye west" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Snapchat

### GET /snapchat/profile

Get Snapchat user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Snapchat username

```
curl "https://www.socialcrawl.dev/v1/snapchat/profile?handle=djkhaled305" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Tavily

### GET /tavily/search

Tavily web search with optional LLM-generated answer

Credit cost: 1 (standard)

Parameters:
- query (required) — The search query — natural-language free text.
- search_depth (optional, enum: basic | advanced | fast | ultra-fast) — Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking.
- topic (optional, enum: general | news | finance) — Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data.
- time_range (optional, enum: day | week | month | year | d | w | m | y) — Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`).
- max_results (optional, integer) — Number of results to return (1–20). Defaults to 5.
- chunks_per_source (optional, integer) — Max relevant chunks returned per source (1–5). Only honoured when `search_depth=advanced`. Defaults to 3.
- include_images (optional, boolean) — Include images alongside the result content.
- include_image_descriptions (optional, boolean) — Include AI-generated descriptions for the returned images.
- include_answer (optional, boolean) — Include an LLM-generated answer string synthesised from the top sources.
- include_raw_content (optional, boolean) — Include the raw HTML/text alongside the cleaned content.
- include_domains (optional, string) — Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`).
- exclude_domains (optional, string) — Comma-separated list of domains to exclude from results.
- country (optional, string) — ISO 3166-1 alpha-2 country code to bias results toward.
- start_date (optional, string) — Inclusive lower bound on result publish date (YYYY-MM-DD).
- end_date (optional, string) — Inclusive upper bound on result publish date (YYYY-MM-DD).

```
curl "https://www.socialcrawl.dev/v1/tavily/search?query=claude opus 4.7 release notes" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tavily/extract

Extract clean content from one or more URLs

Credit cost: 1 (standard)

Parameters:
- urls (required) — Comma-separated list of URLs to extract (max 20).
- extract_depth (optional, enum: basic | advanced) — Extraction strategy. `basic` is the default and faster; `advanced` handles harder pages but takes longer.
- format (optional, enum: markdown | text) — Output format for the extracted content. `markdown` (default) preserves structure; `text` is plain.
- include_images (optional, boolean) — Include images extracted from each URL.
- include_favicon (optional, boolean) — Include the favicon URL for each page.
- timeout (optional, integer) — Per-URL timeout in seconds (1–60).

```
curl "https://www.socialcrawl.dev/v1/tavily/extract?urls=https://en.wikipedia.org/wiki/Lionel_Messi" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tavily/map

Map a website's sitegraph

Credit cost: 1 (standard)

Parameters:
- url (required) — Root URL to begin mapping.
- max_depth (optional, integer) — Maximum link depth from the root URL. Defaults to 1.
- max_breadth (optional, integer) — Maximum number of links followed per level (per page). Defaults to 20.
- limit (optional, integer) — Total number of links the mapper will process before stopping. Defaults to 50.
- instructions (optional, string) — Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation').
- select_paths (optional, string) — Comma-separated regex patterns — only include URLs whose path matches.
- select_domains (optional, string) — Comma-separated regex patterns — only include URLs whose domain matches.
- exclude_paths (optional, string) — Comma-separated regex patterns — exclude URLs whose path matches.
- exclude_domains (optional, string) — Comma-separated regex patterns — exclude URLs whose domain matches.
- allow_external (optional, boolean) — Whether to follow / return links to external domains. Defaults to true.
- timeout (optional, integer) — Maximum time in seconds (10–150).
- categories (optional, string) — Comma-separated list of category hints to bias mapping toward.

```
curl "https://www.socialcrawl.dev/v1/tavily/map?url=https://docs.tavily.com" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tavily/crawl

Crawl a website with LLM-driven path selection

Credit cost: 1 (standard)

Parameters:
- url (required) — Root URL to begin crawling.
- max_depth (optional, integer) — Maximum link depth from the root URL. Defaults to 1.
- max_breadth (optional, integer) — Maximum number of links followed per level (per page). Defaults to 20.
- limit (optional, integer) — Total number of pages the crawler will process before stopping. Defaults to 50.
- instructions (optional, string) — Natural-language instructions for the crawler (e.g. 'Find all product pages with pricing').
- select_paths (optional, string) — Comma-separated regex patterns — only crawl URLs whose path matches.
- select_domains (optional, string) — Comma-separated regex patterns — only crawl URLs whose domain matches.
- exclude_paths (optional, string) — Comma-separated regex patterns — skip URLs whose path matches.
- exclude_domains (optional, string) — Comma-separated regex patterns — skip URLs whose domain matches.
- allow_external (optional, boolean) — Whether to follow links to external domains. Defaults to true.
- extract_depth (optional, enum: basic | advanced) — Per-page extraction strategy. `basic` is faster; `advanced` handles harder pages.
- format (optional, enum: markdown | text) — Output format for extracted content. `markdown` (default) or `text`.
- categories (optional, string) — Comma-separated list of category hints to bias the crawl toward.

```
curl "https://www.socialcrawl.dev/v1/tavily/crawl?url=https://docs.tavily.com" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Threads

### GET /threads/profile

Get Threads user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Threads username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/threads/profile?handle=zuck" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /threads/user/posts

List Threads user posts

Credit cost: 1 (standard)

Parameters:
- handle (required) — Threads username without the @ symbol
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/threads/user/posts?handle=zuck" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /threads/post

Get Threads post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Threads post
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/threads/post?url=https://www.threads.net/@zuck/post/CwABCDEFGHI" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /threads/search

Search Threads posts

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find Threads posts
- start_date (optional, string) — Start date to search for
- end_date (optional, string) — End date to search for
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/threads/search?query=artificial intelligence" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /threads/search/users

Search Threads users

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find Threads users

```
curl "https://www.socialcrawl.dev/v1/threads/search/users?query=tech" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Tiktok

### GET /tiktok/profile

Get TikTok user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — TikTok username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/profile/videos

List TikTok user videos

Credit cost: 1 (standard)

Parameters:
- handle (required) — TikTok username without the @ symbol
- user_id (optional, string) — TikTok user id. Use this for faster responses.
- sort_by (optional, enum: latest | popular) — What to sort by
- max_cursor (optional, string) — Cursor to get more videos. Get 'max_cursor' from previous response.
- region (optional, string) — Region (Country) you want the proxy in. Defaults to US.
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/tiktok/profile/videos?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/post

Get TikTok post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the TikTok video
- get_transcript (optional, boolean) — Get transcript of the video
- region (optional, string) — Region of the proxy. Sometimes you'll need to specify the region if you're not getting a response. Commonly for videos from the Phillipines, in which case you'd use 'PH'. Use 2 letter country codes like US, GB, FR, etc
- trim (optional, boolean) — Set to true to get a trimmed response
- download_media (optional, boolean) — Set to true to download the video/images and get back permanent Supabase URLs. Costs 10 credits if media is found, 1 credit otherwise.

```
curl "https://www.socialcrawl.dev/v1/tiktok/post?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/post/comments

List TikTok post comments

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the TikTok video to fetch comments for
- cursor (optional, integer) — Cursor to get more comments. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/tiktok/post/comments?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/video/comment/replies

List TikTok comment replies

Credit cost: 1 (standard)

Parameters:
- comment_id (required) — TikTok comment ID. This is the cid from the comments endpoint.
- url (required) — TikTok video URL. This is the url from the comments endpoint.
- cursor (optional, integer) — Cursor to get more replies. Get 'cursor' from previous response.

```
curl "https://www.socialcrawl.dev/v1/tiktok/video/comment/replies?comment_id=7623828115408274207&url=https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/search

Search TikTok videos by keyword

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find TikTok videos
- date_posted (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame
- sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by
- region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/tiktok/search?query=cooking recipes" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/trending

Get TikTok trending feed

Credit cost: 5 (advanced)

Parameters:
- region (required) — ISO 3166-1 alpha-2 country code (e.g., US, GB, KR)
- trim (optional, boolean) — Set to true to get a trimmed response.

```
curl "https://www.socialcrawl.dev/v1/tiktok/trending?region=US" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/search/hashtag

Search TikTok by hashtag

Credit cost: 1 (standard)

Parameters:
- hashtag (required) — Hashtag to search for without the # symbol
- region (optional, string) — Region the proxy will be set to. Note: this isn't going to grab you all tiktoks from this region, you're just setting the proxy there.
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/tiktok/search/hashtag?hashtag=fyp" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/search/top

TikTok top search results

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase
- publish_time (optional, enum: yesterday | this-week | this-month | last-3-months | last-6-months | all-time) — Time Frame TikTok was posted
- sort_by (optional, enum: relevance | most-liked | date-posted) — Sort by
- region (optional, string) — Note, this doesn't filter the tiktoks only in a specfic region, it puts the proxy there. Use it in case you want to scrape posts only available for some country. Use 2 letter country codes like US, GB, FR, etc
- cursor (optional, integer) — Cursor to get more videos. Get 'cursor' from previous response.

```
curl "https://www.socialcrawl.dev/v1/tiktok/search/top?query=dance challenge" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/search/users

Search TikTok users

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find TikTok users
- cursor (optional, integer) — Cursor to get more users. Get 'cursor' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/tiktok/search/users?query=cooking" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/user/audience

Get TikTok user audience demographics

Credit cost: 5 (advanced)

Parameters:
- handle (required) — TikTok username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/tiktok/user/audience?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/user/followers

List TikTok user followers (oneOf: handle|user_id)

Credit cost: 1 (standard)

Parameters:
- handle (optional, string) — TikTok username without the @ symbol
- user_id (optional, string) — User id. Use this for faster response times.
- min_time (optional, integer) — Used to paginate. Get 'min_time' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response
- Constraint: one of handle, user_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/tiktok/user/followers?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/user/following

List TikTok user following

Credit cost: 1 (standard)

Parameters:
- handle (required) — TikTok username without the @ symbol
- min_time (optional, integer) — Used to paginate. Get 'min_time' from previous response.
- trim (optional, boolean) — Set to true to get a trimmed response

```
curl "https://www.socialcrawl.dev/v1/tiktok/user/following?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/user/live

Get TikTok user live stream

Credit cost: 1 (standard)

Parameters:
- handle (required) — TikTok username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/tiktok/user/live?handle=charlidamelio" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/post/transcript

Get TikTok video transcript

Credit cost: 10 (premium)

Parameters:
- url (required) — Full URL of the TikTok video
- language (optional, string) — Language of the transcript. 2 letter language code, ie 'en', 'es', 'fr', 'de', 'it', 'ja', 'ko', 'zh'
- use_ai_as_fallback (optional, string) — Set to 'true' to use AI as a fallback to get the transcript if the transcript is not found. Costs 10 credits to use this feature. And only if the video is under 2 minutes.

```
curl "https://www.socialcrawl.dev/v1/tiktok/post/transcript?url=https://www.tiktok.com/@charlidamelio/video/7321485815660738859" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/song

Get TikTok song details

Credit cost: 1 (standard)

Parameters:
- clipId (required) — TikTok sound/song clip ID

```
curl "https://www.socialcrawl.dev/v1/tiktok/song?clipId=7252403792087040774" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/song/videos

List TikTok videos using a song

Credit cost: 1 (standard)

Parameters:
- clipId (optional, string) — TikTok sound/song clip ID
- cursor (optional, integer) — The cursor to get the next page of results.

```
curl "https://www.socialcrawl.dev/v1/tiktok/song/videos?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/songs/popular

Get popular TikTok songs

Credit cost: 5 (advanced)

Parameters:
- page (optional, integer) — Page number
- timePeriod (optional, enum: 7 | 30 | 130) — Time period to get popular songs from
- rankType (optional, enum: popular | surging) — Get popular or surging songs
- newOnBoard (optional, boolean) — New to top 100
- commercialMusic (optional, boolean) — Approved for business use?
- countryCode (optional, enum: AR | AU | AT | BH | BD | BY | BE | BR | BG | KH | CA | CL | CO | HR | CZ | DK | EG | EE | FI | FR | DE | GR | HU | IS | ID | IQ | IE | IL | IT | JP | JO | KZ | KW | LV | LB | LT | LU | MO | MY | MX | MA | MM | NL | NZ | NG | NO | OM | PK | PE | PH | PL | PT | QA | RO | SA | SG | SK | ZA | KR | ES | SE | CH | TW | TH | TR | UA | AE | GB | US | UZ | VN) — Country code to get popular songs from

```
curl "https://www.socialcrawl.dev/v1/tiktok/songs/popular?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/creators/popular

Get popular TikTok creators

Credit cost: 5 (advanced)

Parameters:
- page (optional, integer) — Page number
- sortBy (optional, enum: engagement | follower | avg_views) — Sort creators by engagement, follower count, or average views
- followerCount (optional, enum: 10K-100K | 100K-1M | 1M-10M | 10M+) — Filter by follower count range
- creatorCountry (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code of the creator
- audienceCountry (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code of the audience/follower

```
curl "https://www.socialcrawl.dev/v1/tiktok/creators/popular?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/hashtags/popular

Get popular TikTok hashtags

Credit cost: 5 (advanced)

Parameters:
- period (optional, enum: 7 | 30 | 120) — Time period in days (7, 30, or 120)
- page (optional, integer) — Page number
- countryCode (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code to get popular hashtags from
- newOnBoard (optional, boolean) — Show only newly trending hashtags
- industry (optional, enum: apparel-and-accessories | baby-kids-and-maternity | beauty-and-personal-care | business-services | education | financial-services | food-and-beverage | games | health | home-improvement | household-products | life-services | news-and-entertainment | pets | sports-and-outdoor | tech-and-electronics | travel | vehicle-and-transportation) — Industry to get popular hashtags from.

```
curl "https://www.socialcrawl.dev/v1/tiktok/hashtags/popular?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/videos/popular

Get popular TikTok videos

Credit cost: 5 (advanced)

Parameters:
- period (optional, enum: 7 | 30) — Time period in days (7 or 30)
- page (optional, integer) — Page number
- orderBy (optional, enum: like | hot | comment | repost) — Sort videos by likes, views (hot), comments, or reposts
- countryCode (optional, enum: AU | BR | CA | EG | FR | DE | ID | IL | IT | JP | MY | PH | RU | SA | SG | KR | ES | TW | TH | TR | AE | GB | US | VN) — Country code to get popular videos from

```
curl "https://www.socialcrawl.dev/v1/tiktok/videos/popular?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/shop/product

Get TikTok Shop product details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the TikTok Shop product page
- region (optional, string) — Region the proxy will be set to so you can access products from that country. Use 2 letter country codes like US, GB, FR, etc. For England, don't use UK, use GB.

```
curl "https://www.socialcrawl.dev/v1/tiktok/shop/product?url=https://www.tiktok.com/@shop/product/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/shop/product/reviews

List TikTok Shop product reviews (oneOf: url|product_id)

Credit cost: 1 (standard)

Parameters:
- url (optional, string) — Full URL of the TikTok Shop product page
- product_id (optional, string) — The ID of the product (required if url is not provided)
- page (optional, integer) — The page number of the reviews
- Constraint: one of url, product_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/tiktok/shop/product/reviews?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/shop/products

List TikTok Shop products

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the TikTok Shop page
- cursor (optional, string) — Cursor parameter from the previous response to retrieve the next page of products. Omit for the first page.
- region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to get shop products from. Defaults to US if not provided.

```
curl "https://www.socialcrawl.dev/v1/tiktok/shop/products?url=https://www.tiktok.com/@shop/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/shop/search

Search TikTok Shop products

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find TikTok Shop products
- page (optional, integer) — Page number to retrieve
- region (optional, enum: US | GB | DE | FR | IT | ID | MY | MX | PH | SG | ES | TH | VN | BR | JP | IE) — Region to search shop products in.

```
curl "https://www.socialcrawl.dev/v1/tiktok/shop/search?query=phone case" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /tiktok/user/showcase

List TikTok user showcase products

Credit cost: 1 (standard)

Parameters:
- handle (required) — The handle of the user
- region (optional, string) — Region to put the proxy in
- cursor (optional, string) — The cursor to the next page of products

```
curl "https://www.socialcrawl.dev/v1/tiktok/user/showcase?handle=mrtiktokreviews" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Truthsocial

### GET /truthsocial/profile

Get Truth Social user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Truth Social username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/truthsocial/profile?handle=realDonaldTrump" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /truthsocial/user/posts

List Truth Social user posts (oneOf: handle|user_id)

Credit cost: 1 (standard)

Parameters:
- handle (optional, string) — Truth Social username without the @ symbol
- user_id (optional, string) — Truth Social user id. Use this for faster response times. Trumps is 107780257626128497. It is the 'id' field in the profile endpoint.
- next_max_id (optional, string) — Used to paginate to next page
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of handle, user_id (at least one required)

```
curl "https://www.socialcrawl.dev/v1/truthsocial/user/posts?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /truthsocial/post

Get Truth Social post details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Truth Social post

```
curl "https://www.socialcrawl.dev/v1/truthsocial/post?url=https://truthsocial.com/@realDonaldTrump/posts/123456789" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Twitch

### GET /twitch/profile

Get Twitch streamer profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Twitch username

```
curl "https://www.socialcrawl.dev/v1/twitch/profile?handle=ninja" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitch/clip

Get Twitch clip details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Twitch clip

```
curl "https://www.socialcrawl.dev/v1/twitch/clip?url=https://www.twitch.tv/ninja/clip/ExampleClipSlug" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Twitter

### GET /twitter/profile

Get Twitter user profile

Credit cost: 1 (standard)

Parameters:
- handle (required) — Twitter username without the @ symbol

```
curl "https://www.socialcrawl.dev/v1/twitter/profile?handle=elonmusk" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/user/tweets

List Twitter user tweets

Credit cost: 1 (standard)

Parameters:
- handle (required) — Twitter username without the @ symbol
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/twitter/user/tweets?handle=elonmusk" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/tweet

Get Twitter tweet details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the tweet
- trim (optional, boolean) — Set to true for a trimmed down version of the response

```
curl "https://www.socialcrawl.dev/v1/twitter/tweet?url=https://x.com/elonmusk/status/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/community

Get Twitter community details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Twitter/X community

```
curl "https://www.socialcrawl.dev/v1/twitter/community?url=https://x.com/i/communities/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/community/tweets

List Twitter community tweets

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the Twitter/X community

```
curl "https://www.socialcrawl.dev/v1/twitter/community/tweets?url=https://x.com/i/communities/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/tweet/transcript

Get Twitter video transcript

Credit cost: 10 (premium)

Parameters:
- url (required) — Full URL of the tweet containing a video

```
curl "https://www.socialcrawl.dev/v1/twitter/tweet/transcript?url=https://x.com/elonmusk/status/1234567890" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /twitter/ai-search

AI-powered X (Twitter) search via xAI Grok

Credit cost: 1 (standard)

Parameters:
- query (required) — Natural-language prompt describing what you want to learn from X. The model autonomously searches X using the x_search tool with any handle / date filters you provide.
- from_handles (optional, string) — Comma-separated X handles (max 10). Restricts the search to posts from these accounts only. Mutually exclusive with exclude_handles.
- exclude_handles (optional, string) — Comma-separated X handles (max 10) to exclude from search results. Mutually exclusive with from_handles.
- from_date (optional, string) — ISO 8601 start date (YYYY-MM-DD). Limits the search window to posts on or after this date.
- to_date (optional, string) — ISO 8601 end date (YYYY-MM-DD). Limits the search window to posts on or before this date.

```
curl "https://www.socialcrawl.dev/v1/twitter/ai-search?query=What is @elonmusk saying about xAI this week?" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Utility

### GET /utility/age-gender

Detect age and gender

Credit cost: 10 (premium)

Parameters:
- url (required) — Direct URL of the image to analyze

```
curl "https://www.socialcrawl.dev/v1/utility/age-gender?url=https://example.com/photo.jpg" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Youtube

### GET /youtube/channel

Get YouTube channel info (oneOf: channelId|handle|url)

Credit cost: 1 (standard)

Parameters:
- channelId (optional, string) — YouTube channel ID. Can pass a channelId, handle or url
- handle (optional, string) — YouTube channel handle without the @ symbol
- url (optional, string) — YouTube channel URL. Can pass a channelId, handle or url
- Constraint: one of channelId, handle, url (at least one required)

```
curl "https://www.socialcrawl.dev/v1/youtube/channel?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/channel/videos

List YouTube channel videos (oneOf: channelId|handle)

Credit cost: 1 (standard)

Parameters:
- channelId (optional, string) — YouTube channel ID
- handle (optional, string) — YouTube channel handle without the @ symbol
- sort (optional, enum: latest | popular) — Sort by latest or popular
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- includeExtras (optional, string) — This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. This will slow down the response slightly.
- Constraint: one of channelId, handle (at least one required)

```
curl "https://www.socialcrawl.dev/v1/youtube/channel/videos?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/video

Get YouTube video details

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the YouTube video
- language (optional, string) — Preferred response language (mapped to Accept-Language header; not guaranteed due to YouTube localization behavior). 2 letter language code, ie 'en', 'es', 'fr' etc.

```
curl "https://www.socialcrawl.dev/v1/youtube/video?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/video/comments

List YouTube video comments

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the YouTube video to fetch comments for
- continuationToken (optional, string) — Continuation token to get more comments. Get 'continuationToken' from previous response.
- order (optional, enum: top | newest) — Order of comments

```
curl "https://www.socialcrawl.dev/v1/youtube/video/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/video/comment/replies

List YouTube comment replies

Credit cost: 1 (standard)

Parameters:
- continuationToken (required) — Continuation token for the comment replies. Use 'repliesContinuationToken' from the Comments endpoint, or 'continuationToken' from a previous replies response to paginate.

```
curl "https://www.socialcrawl.dev/v1/youtube/video/comment/replies?continuationToken=Eg0SC2RRdzR3OVdnWGNRGAYygwEaUBIa..." \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/search

Search YouTube videos

Credit cost: 1 (standard)

Parameters:
- query (required) — Search keyword or phrase to find YouTube videos
- uploadDate (optional, enum: today | this_week | this_month | this_year) — Upload date
- sortBy (optional, enum: relevance | popular) — Sort by
- filter (optional, enum: shorts) — Filter by these options. Note this doesn't work when you use either 'uploadDate' or 'sortBy'. It basically only works when you have a query.
- region (optional, string) — 2 letter country code of the country to put the proxy in.
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- includeExtras (optional, string) — This will get you the like + comment count and the description. To get the full details of the video, use the /v1/youtube/video endpoint. *This will slow down the response slightly.*

```
curl "https://www.socialcrawl.dev/v1/youtube/search?query=javascript tutorial" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/channel/shorts

List YouTube channel shorts (oneOf: channelId|handle)

Credit cost: 1 (standard)

Parameters:
- handle (optional, string) — YouTube channel handle without the @ symbol
- channelId (optional, string) — Can pass channelId or handle
- sort (optional, enum: newest | popular) — Sort by newest or popular
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- Constraint: one of channelId, handle (at least one required)

```
curl "https://www.socialcrawl.dev/v1/youtube/channel/shorts?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/community-post

Get YouTube community post

Credit cost: 1 (standard)

Parameters:
- url (required) — Full URL of the YouTube community post

```
curl "https://www.socialcrawl.dev/v1/youtube/community-post?url=https://www.youtube.com/post/UgkxCWeKpIOHLknREsNOF9M_aqz4fKkCERjP" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/playlist

Get YouTube playlist

Credit cost: 1 (standard)

Parameters:
- playlist_id (required) — YouTube playlist ID

```
curl "https://www.socialcrawl.dev/v1/youtube/playlist?playlist_id=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/search/hashtag

Search YouTube by hashtag

Credit cost: 1 (standard)

Parameters:
- hashtag (required) — Hashtag to search for without the # symbol
- continuationToken (optional, string) — Continuation token to get more videos. Get 'continuationToken' from previous response.
- type (optional, enum: all | shorts) — Search for all types of content or only shorts

```
curl "https://www.socialcrawl.dev/v1/youtube/search/hashtag?hashtag=shorts" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/shorts/trending

Get trending YouTube shorts

Credit cost: 5 (advanced)

```
curl "https://www.socialcrawl.dev/v1/youtube/shorts/trending?" \
  -H "x-api-key: sc_your_api_key_here"
```

### GET /youtube/video/transcript

Get YouTube video transcript

Credit cost: 10 (premium)

Parameters:
- url (required) — Full URL of the YouTube video
- language (optional, string) — 2 letter language code, ie 'en', 'es', 'fr' etc. If the transcript is not available in the language you specify, the transcript will be null.

```
curl "https://www.socialcrawl.dev/v1/youtube/video/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "x-api-key: sc_your_api_key_here"
```

---

## Error Codes

| Code | Status | Description |
|---|---|---|
| MISSING_API_KEY | 401 | No x-api-key header provided |
| INVALID_API_KEY | 401 | API key is malformed or not found |
| INSUFFICIENT_CREDITS | 402 | Not enough credits — purchase more at https://www.socialcrawl.dev |
| INVALID_REQUEST | 400 | Missing required parameters |
| ENDPOINT_NOT_FOUND | 404 | Unknown platform or resource |
| RESOURCE_NOT_FOUND | 404 | The requested item was not found on the platform |
| CONCURRENCY_LIMIT | 429 | Too many simultaneous requests (max 50 per key) |
| UPSTREAM_ERROR | 502 | Platform returned an error — credits refunded |
| SERVICE_UNAVAILABLE | 503 | Circuit breaker open — try again shortly, credits refunded |
| INTERNAL_ERROR | 500 | Unexpected error — credits refunded |