Social Fetch

https://www.socialfetch.dev/docs
Admin
Social Fetch is a unified REST API that provides normalized social media data, profiles, posts, and...
Tokens:83,566
Snippets:536
Trust Score:6.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install x402 Buyer Helpers

Source: https://www.socialfetch.dev/docs/integrations/x402

Install the necessary packages to handle x402 payments in a Node.js environment.

```bash
npm install @x402/fetch @x402/evm viem
```

--------------------------------

### Example tool argument

Source: https://www.socialfetch.dev/docs/integrations/mcp

Example JSON argument for a profile retrieval tool call.

```json
{ "handle": "nike" }
```

--------------------------------

### Install TypeScript SDK

Source: https://www.socialfetch.dev/docs/sdk

Command to install the official Social Fetch SDK via npm.

```bash
npm install @socialfetch/sdk
```

--------------------------------

### Install Social Fetch skill from specific path

Source: https://www.socialfetch.dev/docs/integrations/skills

Install the skill directly from the repository path to avoid including other skills in the monorepo.

```bash
npx skills add https://github.com/social-freak-ltd/socialfetch/tree/main/skills/socialfetch
```

--------------------------------

### GET /v1/whoami

Source: https://www.socialfetch.dev/docs/api.mdx

Validates API keys. This endpoint does not charge credits.

```APIDOC
## GET /v1/whoami

### Description
Validates API keys. This endpoint does not charge credits.

### Method
GET

### Endpoint
/v1/whoami
```

--------------------------------

### GET /v1/rumble/channels/videos

Source: https://www.socialfetch.dev/docs/api/v1/rumble/channels/videos/get

Retrieves videos and Shorts from a Rumble channel.

```APIDOC
## GET /v1/rumble/channels/videos

### Description
List videos and Shorts from a Rumble channel.

### Method
GET

### Endpoint
/v1/rumble/channels/videos

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Link to the Rumble channel.
- **cursor** (string) - Optional - Page number from a previous response.

### Request Example
curl "https://api.socialfetch.dev/v1/rumble/channels/videos?url=https://rumble.com/c/StevenCrowder" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the channel was resolved (found, not_found).
- **data.channel** (object) - Resolved channel metadata.
- **data.videos** (array) - Videos returned for the resolved channel.
- **data.shorts** (array) - Shorts returned for the resolved channel.
- **data.page** (object) - Pagination information.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/linkedin/posts/search

Source: https://www.socialfetch.dev/docs/capability-matrix

Searches for LinkedIn posts.

```APIDOC
## GET /v1/linkedin/posts/search

### Description
Search LinkedIn posts.

### Method
GET

### Endpoint
/v1/linkedin/posts/search

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
```

--------------------------------

### GET /health

Source: https://www.socialfetch.dev/docs/capability-matrix

Performs a system health check.

```APIDOC
## GET /health

### Description
Checks the operational status of the API.

### Method
GET

### Endpoint
/health
```

--------------------------------

### GET /v1/facebook/profiles/posts

Source: https://www.socialfetch.dev/docs/capability-matrix

Lists posts from a Facebook profile.

```APIDOC
## GET /v1/facebook/profiles/posts

### Description
List Facebook profile posts.

### Method
GET

### Endpoint
/v1/facebook/profiles/posts

### Parameters
#### Query Parameters
- **url** (string) - Optional - The URL of the Facebook profile.
```

--------------------------------

### GET /v1/facebook/profiles

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieves a Facebook profile by URL.

```APIDOC
## GET /v1/facebook/profiles

### Description
Get Facebook profile information.

### Method
GET

### Endpoint
/v1/facebook/profiles

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the Facebook profile.
```

--------------------------------

### GET /v1/linkedin/jobs

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieves LinkedIn job listings.

```APIDOC
## GET /v1/linkedin/jobs

### Description
Get LinkedIn jobs.

### Method
GET

### Endpoint
/v1/linkedin/jobs

### Parameters
#### Query Parameters
- **url** (string) - Required - The LinkedIn job URL.
```

--------------------------------

### GET /v1/github/profiles/{handle}

Source: https://www.socialfetch.dev/docs/api/v1/github/profiles/handle/get

Retrieves a GitHub profile for a user or organization.

```APIDOC
## GET /v1/github/profiles/{handle}

### Description
Get a GitHub profile for a user or organization.

### Method
GET

### Endpoint
/v1/github/profiles/{handle}

### Parameters
#### Path Parameters
- **handle** (string) - Required - GitHub username to look up, with or without a leading @ (min 1, max 39 chars).

#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the profile was found (found, not_found).
- **data.profile** (object) - Profile details when available.
- **data.metrics** (object) - Profile metrics when available.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/github/repositories

Source: https://www.socialfetch.dev/docs/api/v1/github/repositories/get

Retrieves a single GitHub repository by its URL.

```APIDOC
## GET /v1/github/repositories

### Description
Get a single GitHub repository by URL.

### Method
GET

### Endpoint
/v1/github/repositories

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Full public GitHub repository URL.

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the repository was found (found, not_found).
- **data.repository** (object) - Repository metadata when available.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/rumble/videos

Source: https://www.socialfetch.dev/docs/api/v1/rumble/videos/get

Retrieves metadata for a Rumble video by its URL.

```APIDOC
## GET /v1/rumble/videos

### Description
Retrieves metadata for a Rumble video by providing the video URL. This endpoint returns details such as the video title, description, metrics, and channel information.

### Method
GET

### Endpoint
/v1/rumble/videos

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Link to the Rumble video.

### Request Example
curl "https://api.socialfetch.dev/v1/rumble/videos?url=https://rumble.com/v79xhhm-discovery-why-glenn-wants-israel-to-sue-the-new-york-times.html" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the video was resolved (found, not_found).
- **data.video** (object) - Video details when found.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/balance

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieves the current account credit balance.

```APIDOC
## GET /v1/balance

### Description
Fetches the current account balance.

### Method
GET

### Endpoint
/v1/balance
```

--------------------------------

### GET /v1/whoami

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieves information about the currently authenticated user.

```APIDOC
## GET /v1/whoami

### Description
Returns identity information for the authenticated session.

### Method
GET

### Endpoint
/v1/whoami
```

--------------------------------

### GET /v1/linkedin/posts

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieves a specific LinkedIn post or article.

```APIDOC
## GET /v1/linkedin/posts

### Description
Get LinkedIn post or article.

### Method
GET

### Endpoint
/v1/linkedin/posts

### Parameters
#### Query Parameters
- **url** (string) - Required - The LinkedIn post URL.
```

--------------------------------

### GET /v1/linkedin/companies/posts

Source: https://www.socialfetch.dev/docs/capability-matrix

Lists posts from a LinkedIn company page.

```APIDOC
## GET /v1/linkedin/companies/posts

### Description
List LinkedIn company posts.

### Method
GET

### Endpoint
/v1/linkedin/companies/posts

### Parameters
#### Query Parameters
- **url** (string) - Required - The LinkedIn company URL.
```

--------------------------------

### Get TikTok video transcript via cURL

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/transcript/get

Example request to retrieve a transcript for a specific TikTok video URL using an API key.

```bash
curl "https://api.socialfetch.dev/v1/tiktok/videos/transcript?url=https://www.tiktok.com/@mrbeast/video/7596844935442189598" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Quick Start SDK Usage

Source: https://www.socialfetch.dev/docs/sdk

Basic initialization and request pattern for the Social Fetch client.

```typescript
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const result = await client.tiktok.getProfile({ handle: "charlidamelio" });

if (!result.ok) {
  console.error(result.error.code, result.error.requestId);
  return;
}

console.log(result.value.data.profile);
```

--------------------------------

### Client Configuration

Source: https://www.socialfetch.dev/docs/sdk

Initialize the client using the required API key.

```typescript
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
  apiKey: process.env.SOCIALFETCH_API_KEY!,
});
```

--------------------------------

### GET /v1/balance

Source: https://www.socialfetch.dev/docs/api/v1/balance

Retrieves the current account balance and billing status.

```APIDOC
## GET /v1/balance

### Description
Get remaining credit balance before running large batches of metered tools.

### Method
GET

### Endpoint
/v1/balance

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.balance** (integer) - Spendable credits.
- **data.payg** (integer) - Total PAYG bucket.
- **data.paygSpendable** (integer) - PAYG credits spendable before grace.
- **data.graceDebtCredits** (integer) - Grace buffer for the current unpaid refill episode.
- **data.refillState** (string) - Auto-refill state: healthy, grace, or exhausted.
- **data.billingAlert** (string) - Billing health: none, payment_action_required, or suspended.
- **data.subscriptionIncludedRemaining** (integer) - Included credits left this period.
- **data.subscriptionIncludedTotal** (integer) - Included credits granted this period.
- **data.subscription** (object) - Subscription summary.
- **meta** (object) - Metadata describing the request and billing outcome.

### Request Example
curl "https://api.socialfetch.dev/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Get TikTok profile region via cURL

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/region/get

Retrieve the region code for a specified TikTok handle using a GET request with an API key in the header.

```bash
curl "https://api.socialfetch.dev/v1/tiktok/profiles/charlidamelio/region" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Install Social Fetch agent skill

Source: https://www.socialfetch.dev/docs/integrations/skills

Use this command to add the Social Fetch skill to your agent environment.

```bash
npx skills add social-freak-ltd/socialfetch -s socialfetch
```

--------------------------------

### GET /v1/instagram/profiles/{handle}/highlights

Source: https://www.socialfetch.dev/docs/capability-matrix

List highlights from an Instagram profile.

```APIDOC
## GET /v1/instagram/profiles/{handle}/highlights

### Description
List Instagram profile highlights.

### Method
GET

### Endpoint
/v1/instagram/profiles/{handle}/highlights

### Parameters
#### Path Parameters
- **handle** (string) - Required - The Instagram profile handle.
```

--------------------------------

### GET /v1/twitter/communities/tweets

Source: https://www.socialfetch.dev/docs/api/v1/twitter/communities/tweets/get

Fetches tweets from a Twitter community.

```APIDOC
## GET /v1/twitter/communities/tweets

### Description
List tweets from an X community by community URL.

### Method
GET

### Endpoint
/v1/twitter/communities/tweets

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Community URL to look up (min 1, max 4096 chars).

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether tweet data was returned (found, not_found).
- **data.tweets** (array) - List of tweets returned for the community.
- **data.tweets[].id** (string) - Tweet id (rest_id).
- **data.tweets[].url** (string) - Canonical public URL for this tweet.
- **data.tweets[].text** (string) - Full tweet text.
- **data.tweets[].metrics** (object) - Engagement metrics (views, favorites, retweets, replies, bookmarks, quotes).
```

--------------------------------

### Implement x402 Payment in Node.js

Source: https://www.socialfetch.dev/docs/integrations/x402

Wrap the fetch function with x402 payment handling, registering both Exact and Upto schemes for Base.

```javascript
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { UptoEvmScheme } from "@x402/evm/upto/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(
  process.env.EVM_PRIVATE_KEY as `0x${string}`,
);

const client = new x402Client()
  .register("eip155:8453", new ExactEvmScheme(signer))
  .register("eip155:8453", new UptoEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const res = await fetchWithPayment(
  "https://api.socialfetch.dev/v1/twitter/profiles/elonmusk",
);

console.log(res.status, await res.json());
console.log(res.headers.get("PAYMENT-RESPONSE"));
```

--------------------------------

### Run stdio-only MCP client

Source: https://www.socialfetch.dev/docs/integrations/mcp

Connect to the Social Fetch MCP server using the mcp-remote utility.

```bash
npx mcp-remote https://api.socialfetch.dev/mcp
```

--------------------------------

### GET /v1/twitter/tweets

Source: https://www.socialfetch.dev/docs/api/v1/twitter/tweets/get

Retrieves a single tweet by its URL.

```APIDOC
## GET /v1/twitter/tweets

### Description
Get a single tweet by URL.

### Method
GET

### Endpoint
/v1/twitter/tweets

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Tweet permalink or identifier (min 1 chars, max 4096 chars)
- **trim** (boolean) - Optional - Omit author profile and tweet core for a smaller response

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload
- **data.lookupStatus** (string) - Whether the tweet was found or unavailable (found, not_found)
- **data.author** (object) - Author profile and metrics when not trimmed; null when trim=true or when not found
```

--------------------------------

### Get LinkedIn Jobs

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve job posting details by URL.

```javascript
client.linkedin.getJobs({ urls })
```

--------------------------------

### GET /v1/twitter/hashtags

Source: https://www.socialfetch.dev/docs/api/v1/twitter/hashtags/get

Search X posts by hashtag.

```APIDOC
## GET /v1/twitter/hashtags

### Description
Search X posts by hashtag. Note that this is for hashtag-specific searches, not free-text keyword searches.

### Method
GET

### Endpoint
/v1/twitter/hashtags

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **hashtag** (string) - Required - Hashtag to search for (min 1, max 256 chars).
- **section** (string) - Optional - Optional section filter (top, latest, people, photos, videos). Defaults to 'top'.
- **limit** (number) - Optional - Optional page size (max 20).
- **cursor** (string) - Optional - Opaque pagination cursor returned by a previous response.

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.tweets** (array) - Posts returned for the requested hashtag.
- **data.people** (array) - Profiles returned for the requested hashtag.
```

--------------------------------

### List YouTube channel videos via cURL

Source: https://www.socialfetch.dev/docs/api/v1/youtube/channels/videos/get

Example request to fetch videos for a specific YouTube channel handle using an API key.

```bash
curl "https://api.socialfetch.dev/v1/youtube/channels/videos?handle=charlidamelio" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/threads/users/search

Source: https://www.socialfetch.dev/docs/api/v1/threads/users/search/get

Search Threads users by keyword.

```APIDOC
## GET /v1/threads/users/search

### Description
Search Threads users by keyword.

### Method
GET

### Endpoint
/v1/threads/users/search

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **query** (string) - Required - Search query text for Threads users (min 1 chars, max 512 chars).

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.query** (string) - Search query that was evaluated for this response.
- **data.users** (array) - Users returned for the search query.
- **data.users[].platform** (string) - Social platform for this user (one of: threads).
- **data.users[].handle** (string) - Threads username without the leading @.
- **data.users[].displayName** (string) - Public display name shown for the user, when available.
- **data.users[].avatarUrl** (string) - Profile image URL for the user, when available.
- **data.users[].verified** (boolean) - Whether the user is marked as verified.
- **data.users[].profileUrl** (string) - Canonical public Threads profile URL.
- **data.users[].platformUserId** (string) - Threads user id as a string when available.
- **data.users[].activeOnThreads** (boolean) - Whether the account is reported as active on Threads.
- **data.users[].onboardedToThreads** (boolean) - Whether the account is reported as onboarded to Threads.
- **data.totalUsers** (integer) - Number of users returned in this response.
- **meta** (object) - Metadata describing the request and billing outcome.
- **meta.requestId** (string) - Unique request identifier for tracing this API call.
- **meta.creditsCharged** (integer) - Credits charged for this request.
- **meta.version** (string) - Public API version that served the response.
- **meta.cached** (boolean) - True when served from shared response cache.
```

--------------------------------

### Example balance response during grace period

Source: https://www.socialfetch.dev/docs/credits

A sample JSON response showing a state where payment has failed and the account is consuming the grace buffer.

```json
{
  "data": {
    "balance": 1998,
    "billingAlert": "payment_action_required",
    "paygSpendable": 0,
    "refillState": "grace",
    "graceDebtCredits": 2000
  }
}
```

--------------------------------

### GET /v1/tiktok/profiles/{handle}/videos

Source: https://www.socialfetch.dev/docs/capability-matrix

Lists videos for a specific TikTok profile with support for sorting and pagination.

```APIDOC
## GET /v1/tiktok/profiles/{handle}/videos

### Description
List TikTok profile videos with optional sorting and cursor-based pagination.

### Method
GET

### Endpoint
/v1/tiktok/profiles/{handle}/videos

### Parameters
#### Path Parameters
- **handle** (string) - Required - The TikTok profile handle.

#### Query Parameters
- **userId** (string) - Optional - User identifier.
- **sortBy** (string) - Optional - Sort order: latest, popular.
- **cursor** (string) - Optional - Pagination cursor.

### Response
#### Success Response (200)
- **data.videos** (array) - List of videos.
- **data.page.nextCursor** (string) - Cursor for the next page.
- **data.page.hasMore** (boolean) - Indicates if more results are available.
```

--------------------------------

### Get LinkedIn Post or Article

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve a specific LinkedIn post or article by URL.

```javascript
client.linkedin.getPost({ url })
```

--------------------------------

### Get LinkedIn Profiles

Source: https://www.socialfetch.dev/docs/capability-matrix

Use these methods to retrieve profile data by URL.

```javascript
client.linkedin.getProfiles({ urls }) or client.linkedin.getProfile({ url })
```

--------------------------------

### Ask a question via cURL

Source: https://www.socialfetch.dev/docs/api/v1/web/ask/get

Example request to the /v1/web/ask endpoint using a URL and a natural-language query.

```bash
curl "https://api.socialfetch.dev/v1/web/ask?url=https://www.socialfetch.dev&q=What is this page about?" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/instagram/search/reels

Source: https://www.socialfetch.dev/docs/api/v1/instagram/search/reels/get

Search for Instagram reels by keyword.

```APIDOC
## GET /v1/instagram/search/reels

### Description
Search for public Instagram reels using a keyword query.

### Method
GET

### Endpoint
https://api.socialfetch.dev/v1/instagram/search/reels

### Query Parameters
- **query** (string) - Required - The keyword to search for in reels.

### Request Example
curl "https://api.socialfetch.dev/v1/instagram/search/reels?query=dogs" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data.page.currentPage** (integer) - 1-based page number for this response.
- **data.page.nextPage** (integer|null) - Next page number to request when more reels are available; otherwise null.
- **data.page.hasMore** (boolean) - Whether another page of reels is available.
- **meta.requestId** (string) - Unique request identifier for tracing this API call.
- **meta.creditsCharged** (integer) - Credits charged for this request.
- **meta.version** (string) - Public API version that served the response.
- **meta.cached** (boolean) - True when served from shared response cache.
```

--------------------------------

### Search Threads users via cURL

Source: https://www.socialfetch.dev/docs/api/v1/threads/users/search/get

Example request to search for users matching the query 'shams'. Replace YOUR_API_KEY with your actual API key.

```bash
curl "https://api.socialfetch.dev/v1/threads/users/search?query=shams" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/instagram/search/profiles

Source: https://www.socialfetch.dev/docs/api/v1/instagram/search/profiles/get

Search Instagram profiles by keyword.

```APIDOC
## GET /v1/instagram/search/profiles

### Description
Search Instagram profiles by keyword. This endpoint returns a list of profiles matching the provided query.

### Method
GET

### Endpoint
/v1/instagram/search/profiles

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **query** (string) - Required - Search query text for Instagram profiles (min 1 chars, max 512 chars).
- **cursor** (string) - Optional - Opaque pagination cursor returned by a previous response.

### Request Example
curl "https://api.socialfetch.dev/v1/instagram/search/profiles?query=fitness coach" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.query** (string) - Search query that was evaluated.
- **data.profiles** (array) - Profiles returned for the search query.
- **data.totalProfiles** (integer) - Number of profiles returned.
- **data.page** (object) - Pagination information.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### List Pinterest board pins with cURL

Source: https://www.socialfetch.dev/docs/api/v1/pinterest/boards/pins/get

Example request to fetch pins from a specific Pinterest board URL using an API key.

```bash
curl "https://api.socialfetch.dev/v1/pinterest/boards/pins?url=https://www.pinterest.com/lizmrodgers/moms-night/" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Get LinkedIn Organizations

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve organization page data, including companies and schools.

```javascript
client.linkedin.getOrganizations({ urls }) or client.linkedin.getOrganization({ url })
```

--------------------------------

### Get LinkedIn Post Transcript

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve the transcript for a specific LinkedIn post.

```javascript
client.linkedin.getPostTranscript({ url })
```

--------------------------------

### Retrieve TikTok Shop product details via cURL

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/products/get

Use this command to fetch product information by providing the product URL as a query parameter and your API key in the headers.

```bash
curl "https://api.socialfetch.dev/v1/tiktok/products?url=https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/github/profiles/{handle}/following

Source: https://www.socialfetch.dev/docs/api/v1/github/profiles/handle/following/get

Retrieves the list of accounts followed by a GitHub profile identified by their handle.

```APIDOC
## GET /v1/github/profiles/{handle}/following

### Description
List accounts a GitHub profile follows.

### Method
GET

### Endpoint
/v1/github/profiles/{handle}/following

### Parameters
#### Path Parameters
- **handle** (string) - Required - GitHub username whose following list should be listed.

#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor from a previous response.

### Request Example
curl "https://api.socialfetch.dev/v1/github/profiles/torvalds/following" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether following could be listed for this handle (found, not_found).
- **data.following** (array) - Accounts followed by the requested profile.
- **data.page** (object) - Pagination state for the current page.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### Get LinkedIn Company Page

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve data specifically for a LinkedIn company page.

```javascript
client.linkedin.getCompany({ url })
```

--------------------------------

### Get LinkedIn Ad Library Ad

Source: https://www.socialfetch.dev/docs/capability-matrix

Retrieve details for a specific ad from the LinkedIn Ad Library.

```javascript
client.linkedin.getAdLibraryAd({ adId?, url? })
```

--------------------------------

### Retrieve Twitch profile videos via cURL

Source: https://www.socialfetch.dev/docs/api/v1/twitch/profiles/handle/videos/get

Example request to fetch videos for a specific Twitch handle sorted by time.

```bash
curl "https://api.socialfetch.dev/v1/twitch/profiles/ishowspeed/videos?sortBy=time" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/youtube/videos

Source: https://www.socialfetch.dev/docs/api/v1/youtube/videos/get

Retrieves details for a single YouTube video.

```APIDOC
## GET /v1/youtube/videos

### Description
Get a single YouTube video by URL.

### Method
GET

### Endpoint
/v1/youtube/videos
```

--------------------------------

### Configure Cursor MCP

Source: https://www.socialfetch.dev/docs/integrations/mcp

Add the Social Fetch MCP server to your Cursor configuration file.

```json
{
  "mcpServers": {
    "socialfetch": {
      "url": "https://api.socialfetch.dev/mcp"
    }
  }
}
```

--------------------------------

### GET /v1/youtube/community-posts

Source: https://www.socialfetch.dev/docs/api/v1/youtube/community-posts/get

Retrieves a YouTube community post by its URL.

```APIDOC
## GET /v1/youtube/community-posts

### Description
Retrieves a YouTube community post by its public URL.

### Method
GET

### Endpoint
/v1/youtube/community-posts

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Public YouTube community post URL (min 1 chars, max 4096 chars)

### Request Example
curl "https://api.socialfetch.dev/v1/youtube/community-posts?url=https://www.youtube.com/post/Ugkxvj2KoApYAXoqLWnKVr6zZe5JjeHrQeP8" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the community post was resolved (found, not_found).
- **data.post** (object) - Community post details.
- **data.channel** (object) - Publishing channel details.
- **data.media** (object) - Media attached to the post.
- **data.metrics** (object) - Engagement metrics.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/twitter/tweets/transcript

Source: https://www.socialfetch.dev/docs/api/v1/twitter/tweets/transcript/get

Retrieves the transcript for a video tweet by its URL.

```APIDOC
## GET /v1/twitter/tweets/transcript

### Description
Get the transcript for a video tweet by URL. This endpoint is for video tweets only and may take longer than typical lookups.

### Method
GET

### Endpoint
/v1/twitter/tweets/transcript

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Tweet permalink or identifier (min 1 chars, max 4096 chars)

### Request Example
curl "https://api.socialfetch.dev/v1/twitter/tweets/transcript?url=https://x.com/TheoVon/status/1916982720317821050" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Outcome of the transcript lookup (found, not_found, lookup_failed).
- **data.tweet** (object) - Tweet identity when the lookup resolved.
- **data.tweet.url** (string) - Public URL of the tweet.
- **data.transcript** (string) - Plain transcript text when available.
- **meta** (object) - Metadata describing the request and billing outcome.
- **meta.requestId** (string) - Unique request identifier.
- **meta.creditsCharged** (integer) - Credits charged for this request.
- **meta.version** (string) - Public API version.
- **meta.cached** (boolean) - True when served from shared response cache.
```

--------------------------------

### GET /v1/pinterest/profiles/{handle}/boards

Source: https://www.socialfetch.dev/docs/api/v1/pinterest/profiles/handle/boards/get

Retrieves a list of public boards for a given Pinterest profile handle.

```APIDOC
## GET /v1/pinterest/profiles/{handle}/boards

### Description
List public boards for a Pinterest profile.

### Method
GET

### Endpoint
/v1/pinterest/profiles/{handle}/boards

### Parameters
#### Path Parameters
- **handle** (string) - Required - Pinterest username whose boards should be listed (min 1, max 64 chars).

#### Query Parameters
- **cursor** (string) - Optional - Opaque pagination cursor returned by a previous response.
- **trim** (boolean) - Optional - When true, returns a smaller response with fewer fields.

### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the profile was found (found, not_found).
- **data.boards** (array) - Boards returned for this request.
- **data.page** (object) - Pagination state for the current response.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### List TikTok Shop product reviews via cURL

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/products/reviews/get

Retrieves product reviews by providing the product URL as a query parameter and an API key in the request header.

```bash
curl "https://api.socialfetch.dev/v1/tiktok/products/reviews?url=https://www.tiktok.com/shop/pdp/cat-nail-clipper-by-potaroma-adjustable-sizes-built-in-file-safe-for-kittens-cats/1731578642912612516" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/tiktok/videos

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/videos/get

Retrieves a single TikTok video by URL.

```APIDOC
## GET /v1/tiktok/videos

### Description
Get a single TikTok video by URL.

### Method
GET

### Endpoint
/v1/tiktok/videos
```

--------------------------------

### Monitor balance and billing alerts

Source: https://www.socialfetch.dev/docs/credits

Use this pattern to check credit levels and billing status before executing large jobs.

```javascript
const { data } = await client.billing.getBalance();
const MIN_CREDITS = 1_000;

if (data.billingAlert !== "none" || data.balance < MIN_CREDITS) {
  notifyOps(); // fix payment in the dashboard and/or buy a pack
}
```

--------------------------------

### GET /v1/twitter/hashtags

Source: https://www.socialfetch.dev/docs/api/v1/twitter/hashtags/get

Retrieves posts associated with a specific hashtag.

```APIDOC
## GET /v1/twitter/hashtags

### Description
Retrieves a list of posts associated with the provided hashtag.

### Method
GET

### Endpoint
/v1/twitter/hashtags

### Parameters
#### Query Parameters
- **hashtag** (string) - Required - The hashtag to search for (e.g., #trending).

### Request Example
curl "https://api.socialfetch.dev/v1/twitter/hashtags?hashtag=#trending" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data.people** (array) - List of account objects associated with the posts.
- **data.page** (object) - Pagination information including nextCursor and hasMore.
- **meta** (object) - Metadata including requestId, creditsCharged, and version.
```

--------------------------------

### GET /v1/truthsocial/posts

Source: https://www.socialfetch.dev/docs/api/v1/truthsocial/posts/get

Retrieves a Truth Social post by URL.

```APIDOC
## GET /v1/truthsocial/posts

### Description
Retrieves a Truth Social post by its URL.

### Method
GET

### Endpoint
/v1/truthsocial/posts
```

--------------------------------

### List GitHub repositories via cURL

Source: https://www.socialfetch.dev/docs/api/v1/github/profiles/handle/repositories/get

Use this command to fetch public repositories for a specific GitHub user by providing their handle and your API key.

```bash
curl "https://api.socialfetch.dev/v1/github/profiles/torvalds/repositories" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/tiktok/shop/products/search

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/shop/products/search/get

Search products in TikTok Shop by keyword.

```APIDOC
## GET /v1/tiktok/shop/products/search

### Description
Search products in TikTok Shop by keyword.

### Method
GET

### Endpoint
/v1/tiktok/shop/products/search

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **query** (string) - Required - Search query text for TikTok Shop products.
- **page** (number) - Optional - 1-based results page number.
- **region** (string) - Optional - Country or region code (US, GB, DE, FR, IT, ID, MY, MX, PH, SG, ES, TH, VN, BR, JP, IE).

### Request Example
curl "https://api.socialfetch.dev/v1/tiktok/shop/products/search?query=shoes" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.query** (string) - Search query that was evaluated.
- **data.products** (array) - Products returned for the requested page.
- **data.totalProducts** (integer) - Total matching products reported.
- **data.page** (object) - Pagination state.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### Fetch trending repositories with cURL

Source: https://www.socialfetch.dev/docs/api/v1/github/trending/repositories/get

Use this command to retrieve trending repositories by specifying the language and time window parameters.

```bash
curl "https://api.socialfetch.dev/v1/github/trending/repositories?language=value&since=daily" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/threads/posts

Source: https://www.socialfetch.dev/docs/api/v1/threads/posts/get

Retrieves a single Threads post by its URL.

```APIDOC
## GET /v1/threads/posts

### Description
Get a single Threads post by URL.

### Method
GET

### Endpoint
/v1/threads/posts

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **url** (string) - Required - Link to the Threads post.
- **trim** (boolean) - Optional - When true, returns a smaller response with fewer fields.

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the post was found (found, not_found).
- **data.post** (object) - Primary post when found.
- **data.author** (object) - Author when found.
- **data.metrics** (object) - Engagement metrics for a Threads post.
- **data.media** (object) - Primary media payload for the post.
- **data.replies** (array) - Top-level replies when available.
```

--------------------------------

### List GitHub profile following with cURL

Source: https://www.socialfetch.dev/docs/api/v1/github/profiles/handle/following/get

Example request to retrieve the list of accounts followed by the GitHub user 'torvalds'. Replace 'YOUR_API_KEY' with your actual Social Fetch API key.

```bash
curl "https://api.socialfetch.dev/v1/github/profiles/torvalds/following" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/pinterest/pins

Source: https://www.socialfetch.dev/docs/api/v1/pinterest/pins/get

Fetch a public Pinterest pin by URL.

```APIDOC
## GET /v1/pinterest/pins

### Description
Fetch a public Pinterest pin by URL.

### Method
GET

### Endpoint
/v1/pinterest/pins
```

--------------------------------

### GET /v1/soundcloud/profiles/{handle}

Source: https://www.socialfetch.dev/docs/api/v1/soundcloud/profiles/handle/get

Retrieves a SoundCloud profile by its handle. Requires an API key in the header.

```APIDOC
## GET /v1/soundcloud/profiles/{handle}

### Description
Retrieves a SoundCloud profile by handle. Returns profile details, metrics, and request metadata.

### Method
GET

### Endpoint
/v1/soundcloud/profiles/{handle}

### Parameters
#### Path Parameters
- **handle** (string) - Required - SoundCloud handle to look up, with or without a leading @.

#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the profile was found (found, not_found).
- **data.profile** (object) - Profile details when available.
- **data.metrics** (object) - Profile metrics when available.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### Retrieve account balance via cURL

Source: https://www.socialfetch.dev/docs/api/v1/balance

Use this request to fetch current credit and billing information. Replace YOUR_API_KEY with your actual API key.

```bash
curl "https://api.socialfetch.dev/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### GET /v1/tiktok/profiles/{handle}/showcase-products

Source: https://www.socialfetch.dev/docs/api/v1/tiktok/profiles/handle/showcase-products/get

Fetches the list of products featured on a TikTok profile's showcase. Note that an empty products array may indicate a private profile or no products, so checking the profile lookup status is recommended.

```APIDOC
## GET /v1/tiktok/profiles/{handle}/showcase-products

### Description
List products featured on a creator's TikTok showcase by handle.

### Method
GET

### Endpoint
/v1/tiktok/profiles/{handle}/showcase-products

### Parameters
#### Path Parameters
- **handle** (string) - Required - TikTok handle whose profile showcase products should be listed.

#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor returned by a previous response.
- **region** (string) - Optional - Optional ISO 3166-1 country code for the request.

### Request Example
curl "https://api.socialfetch.dev/v1/tiktok/profiles/mrtiktokreviews/showcase-products" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.products** (array) - Products shown on the TikTok profile showcase.
- **data.page** (object) - Pagination state for the current response.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/linkedin/jobs/search

Source: https://www.socialfetch.dev/docs/api/v1/linkedin/jobs/search/get

Search LinkedIn jobs by keyword and filters.

```APIDOC
## GET /v1/linkedin/jobs/search

### Description
Search LinkedIn jobs by keyword and filters. Note that this search usually takes around one and a half minutes to complete.

### Method
GET

### Endpoint
/v1/linkedin/jobs/search

### Cost
2 credits per record
```

--------------------------------

### GET /v1/twitch/profiles/{handle}

Source: https://www.socialfetch.dev/docs/api/v1/twitch/profiles/handle/get

Fetches a Twitch profile for a channel by handle. Requires an API key in the header.

```APIDOC
## GET /v1/twitch/profiles/{handle}

### Description
Get a Twitch profile for a channel by handle.

### Method
GET

### Endpoint
/v1/twitch/profiles/{handle}

### Parameters
#### Path Parameters
- **handle** (string) - Required - Twitch handle to look up, with or without a leading @. (min 1 chars, max 64 chars)

#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

### Request Example
curl "https://api.socialfetch.dev/v1/twitch/profiles/ishowspeed" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.lookupStatus** (string) - Whether the profile was found (found, not_found).
- **data.profile** (object) - Profile details when available.
- **data.metrics** (object) - Profile metrics when available.
- **data.recentVideos** (array) - Recent videos or broadcasts from the channel.
- **data.similarStreamers** (array) - Similar streamers suggested for the channel.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/pinterest/search

Source: https://www.socialfetch.dev/docs/api/v1/pinterest/search/get

Search public Pinterest pins by keyword.

```APIDOC
## GET /v1/pinterest/search

### Description
Search public Pinterest pins by keyword.

### Method
GET

### Endpoint
/v1/pinterest/search

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **query** (string) - Required - Search query text for Pinterest pins.
- **cursor** (string) - Optional - Opaque pagination cursor returned by a previous response.
- **trim** (boolean) - Optional - When true, returns a smaller response with fewer fields.

### Request Example
curl "https://api.socialfetch.dev/v1/pinterest/search?query=Italian Pot Roast" \
  -H "x-api-key: YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.query** (string) - Search query that was evaluated for this response.
- **data.pins** (array) - Matching Pinterest pins.
- **data.page** (object) - Pagination state for the current response.
- **meta** (object) - Metadata describing the request and billing outcome.
```

--------------------------------

### GET /v1/hackernews/search

Source: https://www.socialfetch.dev/docs/api/v1/hackernews/search/get

Search Hacker News by keyword or other criteria.

```APIDOC
## GET /v1/hackernews/search

### Description
Search Hacker News by keyword. This endpoint allows for full-text search and various filtering options.

### Method
GET

### Endpoint
/v1/hackernews/search

### Parameters
#### Headers
- **x-api-key** (string) - Required - API key (sfk_...)

#### Query Parameters
- **query** (string) - Optional - Full-text search query. Required unless frontPageOnly, author, domain, or url is set.
- **type** (string) - Optional - Content type filter. Default: all. Options: all, story, comment, ask_hn, show_hn, launch_hn, job, poll.
- **sort** (string) - Optional - Ranking mode. Default: popularity. Options: popularity, date.
- **dateRange** (string) - Optional - Creation-time window. Default: all. Options: 24h, week, month, year, all.
- **page** (integer) - Optional - Zero-based page index (0-49).
- **pageSize** (integer) - Optional - Hits per page. Default: 20.
- **frontPageOnly** (boolean) - Optional - When true, restrict results to current front-page items.
- **searchStoryText** (boolean) - Optional - Include story/comment text in searchable fields. Default: true.
- **searchAuthor** (boolean) - Optional - When true, include author username in the searchable fields.
- **prefix** (boolean) - Optional - When true, enable prefix matching for query tokens.
- **typoTolerance** (boolean) - Optional - Enable typo tolerance. Default: true.
- **author** (string) - Optional - Restrict results to items by this Hacker News username.
- **domain** (string) - Optional - Restrict search to story URLs matching this domain.
- **url** (string) - Optional - Restrict search to story URLs matching this URL substring.
- **minPoints** (integer) - Optional - Minimum points/score filter.

### Response
#### Success Response (200)
- **data** (object) - Endpoint-specific response payload.
- **data.hits** (array) - Search hits for this page.
- **data.page** (object) - Pagination information.
- **meta** (object) - Metadata describing the request and billing outcome.
```
Tokens:
Raw