# Social media data API for social listening: mentions, posts, search, comments and profiles (Social Media Data API)

> Social media data API for social listening: mentions, posts, search, comments and profiles from Bluesky, Hacker News, X (Twitter), Reddit, TikTok, Instagram, YouTube, Threads, the Meta Ad Library, LinkedIn company pages, in one JSON schema, paid per call over x402 with USDC on Base. No account, no API key. $0.01-$0.025 a call. Operated by Duo Leads, hello@duoleads.com.

How to pay: Every data route is paid per call over x402 v2 (scheme exact): HTTP 402 plus USDC on Base (CAIP-2 eip155:8453), settled through the Coinbase CDP facilitator. An unpaid request returns 402 with a base64 `PAYMENT-REQUIRED` header (price, payTo, asset) and a JSON body with a hint. Sign an EIP-3009 authorization for exactly that amount and send the request with its required parameters and a base64 `PAYMENT-SIGNATURE` header; the 200 response carries a base64 `PAYMENT-RESPONSE` receipt. Malformed input (400), unknown paths (404) and the wrong method (405) are answered before the paywall and never charged. An account, post or video that does not exist, or a search without matches, is a 404, and a total upstream failure (nothing to answer) or a capacity limit is a 503: in every one of these cases your authorization is NOT settled. A partial answer IS charged: a 200 with `complete: false` because one part failed (`platforms_missing` or `posts_missing` names it; a Hacker News reply that failed to load is left out).

Methods: every route is a GET with query parameters. Also accepts POST with the same parameters as a JSON object body (numbers may be JSON numbers), or the same query string with an empty body. Unknown parameters are a free 400 either way; any other method is a free 405.

## Quick start

Try it from a terminal: `npx agentcash try https://social.duoleads.com`

Python (requests):

```python
# pip install "x402[requests,evm]"
import os
from eth_account import Account
from x402 import x402ClientSync
from x402.http.clients import x402_requests
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
client = x402ClientSync()
register_exact_evm_client(client, EthAccountSigner(Account.from_key(os.environ["PRIVATE_KEY"])))  # a Base wallet holding USDC
session = x402_requests(client)  # pays the 402 and retries for you
r = session.get("https://social.duoleads.com/v1/social/mentions?q=open+source&days=7", timeout=30)
print(r.status_code, r.json())
```

TypeScript (fetch):

```ts
// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`); // a Base wallet holding USDC
const pay = wrapFetchWithPayment(fetch, new x402Client().register("eip155:8453", new ExactEvmScheme(account)));
const res = await pay("https://social.duoleads.com/v1/social/mentions?q=open+source&days=7", { signal: AbortSignal.timeout(30_000) });
process.stdout.write(`${res.status} ${JSON.stringify(await res.json())}\n`);
```

Most paid answers take 1-5 s, some up to about 20 s: give your HTTP client a timeout of at least 30 s. The payment settles only after the answer is ready, so a call that fails before that is never charged.

A bare URL without any parameters answers with the 402 (that is how discovery probes see the price); a request with missing or malformed parameters is a free 400 that says what would be accepted.

## Endpoints

- GET [/v1/bluesky/search](https://social.duoleads.com/docs#bluesky-search) ($0.01, MCP tool `bluesky_search`): Bluesky Posts & Search: find public Bluesky posts by keyword, phrase, hashtag or from:handle through the AT Protocol AppView, newest first. Per post the text, author handle and display name, likes, replies, reposts, language, media links, time and URL, in one schema shared by every platform; next_cursor gives the next page. Social listening on Bluesky for brands, products and topics. Bad input is free; not found or no match is not charged.
- GET [/v1/bluesky/posts](https://social.duoleads.com/docs#bluesky-posts) ($0.01, MCP tool `bluesky_posts`): Bluesky Account Posts Feed: the latest public posts and replies of one Bluesky account (a handle such as name.bsky.social, a DID or a bsky.app profile URL), reposts left out. Per post the text, likes, replies, reposts, language, media links, time and URL in the shared social schema; next_cursor pages back through the feed. Bad input is free; not found or no match is not charged.
- GET [/v1/bluesky/profile](https://social.duoleads.com/docs#bluesky-profile) ($0.01, MCP tool `bluesky_profile`): Bluesky Profile Lookup: one public Bluesky account by handle, DID or bsky.app URL: display name, bio, follower, following and post counts, verification, avatar link, creation time and DID, in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/hackernews/search](https://social.duoleads.com/docs#hackernews-search) ($0.01, MCP tool `hackernews_search`): Hacker News Search & Stories: full-text search of Hacker News stories or comments (HN Search by Algolia). Per hit the title, text, author, points, comment count, linked URL, time and item URL in the shared social schema; next_cursor gives the next page. Tech news, launches and developer discussion for market and competitor research. Bad input is free; not found or no match is not charged.
- GET [/v1/hackernews/thread](https://social.duoleads.com/docs#hackernews-thread) ($0.01, MCP tool `hackernews_thread`): Hacker News Comments & Threads: one Hacker News story or comment by id or news.ycombinator.com URL with its direct replies (up to 8 per call, next_cursor for more), deleted and dead replies skipped. Per item the text as plain text, author, score, reply count, parent and time in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/social/mentions](https://social.duoleads.com/docs#social-mentions) ($0.01, MCP tool `social_mentions`): Social Mentions & Sentiment: daily mention counts, distinct authors and mean VADER sentiment for a brand, product or topic over the last 1-7 days, plus the top 10 co-occurring terms. Sources: Bluesky and Hacker News, plus Reddit and X (latest, newest first) when available. One page per source: days beyond its reach come back truncated (coverage_from). Aggregate only, no text, no authors; a day under 20 known authors is suppressed. Bad input is free; not found or no match is not charged.
- GET [/v1/x/search](https://social.duoleads.com/docs#x-search) ($0.02, MCP tool `x_search`): Twitter API: Tweet Search: the latest public tweets on X matching a keyword or phrase, newest first. Per tweet the text, author handle and name, verification, followers, likes, replies, retweets, views, language, time and URL in one schema shared by every platform; parent_id names the replied-to or quoted tweet; next_cursor gives the next page. For social listening, brand monitoring and research. Bad input is free; not found or no match is not charged.
- GET [/v1/x/posts](https://social.duoleads.com/docs#x-posts) ($0.02, MCP tool `x_posts`): Twitter API: User Tweets: the latest public tweets of one X (Twitter) account by handle or x.com URL, newest first. Per tweet the text, author handle and name, verification, followers, likes, replies, retweets, views, language, reply or quote parent, time and URL in the shared social schema; next_cursor gives the next page. Bad input is free; not found or no match is not charged.
- GET [/v1/x/profile](https://social.duoleads.com/docs#x-profile) ($0.02, MCP tool `x_profile`): Twitter API: User Profile: one public X (Twitter) account by handle or x.com URL: display name, bio, followers, following, post count, verification, avatar link and creation time, in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/reddit/search](https://social.duoleads.com/docs#reddit-search) ($0.02, MCP tool `reddit_search`): Reddit Posts & Subreddit Search: search public Reddit posts by keyword, within one subreddit, or list a subreddit's newest posts. Per post the title, text, subreddit, author, upvotes, comment count, linked URL, time and permalink in the shared social schema; next_cursor gives the next page. Forum research and social listening. Bad input is free; not found or no match is not charged.
- GET [/v1/reddit/comments](https://social.duoleads.com/docs#reddit-comments) ($0.02, MCP tool `reddit_comments`): Reddit Post Comments: one Reddit post by id or URL with its comment thread (up to 3 reply levels, deleted and removed comments left out). Per comment the text, author, upvotes, parent, subreddit, time and permalink in the shared social schema; next_cursor gives more comments. Bad input is free; not found or no match is not charged.
- GET [/v1/tiktok/videos](https://social.duoleads.com/docs#tiktok-videos) ($0.02, MCP tool `tiktok_videos`): TikTok Profile & Videos: the latest public videos of one TikTok account by handle or tiktok.com/@ URL. Per video the caption, plays, likes, comments, shares, language, cover image link, time and URL, with the creator's name, verification and followers, in the shared social schema; next_cursor pages back. Bad input is free; not found or no match is not charged.
- GET [/v1/tiktok/search](https://social.duoleads.com/docs#tiktok-search) ($0.02, MCP tool `tiktok_search`): TikTok Video Search: search public TikTok videos by keyword or hashtag. Per video the caption, creator handle, name, verification and followers, plays, likes, comments, shares, cover image link, time and URL in the shared social schema; next_cursor gives the next page. Trend and hashtag research. Bad input is free; not found or no match is not charged.
- GET [/v1/instagram/profile](https://social.duoleads.com/docs#instagram-profile) ($0.02, MCP tool `instagram_profile`): Instagram Profile & Posts: one public Instagram account by handle or URL: name, bio, followers, following, post count, verification, then its recent posts and reels with caption, likes, comments, views, image link and time, in the shared social schema; next_cursor pages through the full post feed. Bad input is free; not found or no match is not charged.
- GET [/v1/youtube/transcript](https://social.duoleads.com/docs#youtube-transcript) ($0.02, MCP tool `youtube_transcript`): YouTube Transcript & Captions: the caption transcript of one YouTube video by id or URL (watch, shorts, live, youtu.be): the full text plus timed segments with start and end in milliseconds and the caption language. Video to text for summaries and research. A video without captions is not charged. Bad input is free; not found or no match is not charged.
- GET [/v1/youtube/comments](https://social.duoleads.com/docs#youtube-comments) ($0.02, MCP tool `youtube_comments`): YouTube Video Comments: the public comments on one YouTube video by id or URL. Per comment the text, author channel handle, verification, likes, reply count, time and link in the shared social schema; next_cursor gives the next page. Audience feedback and sentiment research. Bad input is free; not found or no match is not charged.
- GET [/v1/threads/posts](https://social.duoleads.com/docs#threads-posts) ($0.02, MCP tool `threads_posts`): Threads Posts & Replies: the recent public posts of one Threads account by handle or threads.com URL. Per post the text, likes, replies, reposts, time and URL, with the author's handle and verification, in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/facebook/ads](https://social.duoleads.com/docs#facebook-ads) ($0.02, MCP tool `facebook_ads`): Facebook Ad Library Search: search the public Meta Ad Library by keyword for ads on Facebook and Instagram. Per ad the page name, ad text, active status, start and end dates, publisher platforms, call to action, landing link and media links in the shared social schema; next_cursor gives the next page. Competitor ad research. Bad input is free; not found or no match is not charged.
- GET [/v1/social/search](https://social.duoleads.com/docs#social-search) ($0.025, MCP tool `social_search`): Social Search Across Platforms: one keyword search on Reddit and TikTok, plus X (Twitter) when its key is enabled, at once (choose 1-3), run in parallel. Posts and videos from every platform in one shared schema with text, author, likes, replies, reposts, views, time and URL; platforms_missing names any platform that failed (such a partial answer is charged), next_cursor continues every platform. Bad input is free; not found or no match is not charged.
- GET [/v1/social/audience](https://social.duoleads.com/docs#social-audience) ($0.02, MCP tool `social_audience`): Audience & Engagement Stats: numbers only for one TikTok, Instagram, YouTube or Threads account, or X when its key is enabled: followers, following, posts, and the average likes, comments and views over its last 20 posts, with the engagement rate in percent. No follower names, no post text. Influencer vetting and benchmarking. Bad input is free; not found or no match is not charged.
- GET [/v1/social/accounts](https://social.duoleads.com/docs#social-accounts) ($0.02, MCP tool `social_accounts`): Creator & Brand Account Search: find creator and brand accounts on TikTok, Instagram or Threads by name or keyword. Only verified accounts or accounts with 10,000+ followers are returned (the rest counted in filtered_out); Threads search gives no follower counts and Instagram only for its first 10 results, so beyond those only verified accounts qualify. Per account the handle, name, bio, followers, following, posts and verification. Bad input is free; not found or no match is not charged.
- GET [/v1/linkedin/company](https://social.duoleads.com/docs#linkedin-company) ($0.02, MCP tool `linkedin_company`): LinkedIn Company Page Data: one LinkedIn company page by URL or page name: name, description, industry, size, employee count, headquarters, website, founding year, type, specialties and logo link, plus its recent posts (posts=1 adds the post feed with next_cursor). Company pages only, personal profiles are refused for free. B2B research. Bad input is free; not found or no match is not charged.
- GET [/v1/social/people](https://social.duoleads.com/docs#social-people) ($0.02, MCP tool `people_search`): Social Profile People Search: search public TikTok, Instagram or Threads profiles by name or keyword, unfiltered. Per profile the handle, name, bio, followers, following, posts and verification in the shared social schema; next_cursor on TikTok. Bad input is free; not found or no match is not charged.
- GET [/v1/tiktok/followers](https://social.duoleads.com/docs#tiktok-followers) ($0.02, MCP tool `tiktok_followers`): TikTok Followers List: the public followers of one TikTok account by handle, one page per call with next_cursor. Per follower the handle, name, bio, followers, following, posts and verification in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/tiktok/following](https://social.duoleads.com/docs#tiktok-following) ($0.02, MCP tool `tiktok_following`): TikTok Following List: the public accounts one TikTok account follows, by handle, one page per call with next_cursor. Per account the handle, name, bio, followers, following, posts and verification in the shared social schema. Bad input is free; not found or no match is not charged.
- GET [/v1/linkedin/profile](https://social.duoleads.com/docs#linkedin-profile) ($0.02, MCP tool `linkedin_profile`): LinkedIn Profile Lookup: one public LinkedIn profile by linkedin.com/in/ URL: name, followers, about text and photo link in the shared social schema. Experience, education and contact data are not returned. Bad input is free; not found or no match is not charged.

## Answers

Every 200 answer has the same envelope: `platform`, `query` (the normalised input), `as_of` (when the data was fetched), `complete` (false when part of the data could not be fetched; such a partial answer is charged and never cached), `items` (posts, comments, videos, ads, profiles or company pages in ONE schema: type, platform, id, url, created_at, text, author {handle, display_name, verified, followers}, metrics {likes, replies, reposts, views}, lang, media_urls, parent_id), `next_cursor` (pass it as `cursor` for the next page; null at the end), `source`, `disclaimer` and `request_id`. Media are links, never bytes. Answers may come from a short cache (5 minutes for posts, search and comments, 15 for profiles and aggregates, 1 hour for transcripts).

## Examples

- curl -i 'https://social.duoleads.com/v1/bluesky/search?q=open+source&limit=10'
- curl -i 'https://social.duoleads.com/v1/bluesky/posts?handle=bsky.app&limit=10'
- curl -i 'https://social.duoleads.com/v1/bluesky/profile?handle=bsky.app'
- curl -i 'https://social.duoleads.com/v1/hackernews/search?q=open+source&type=story&limit=10'
- curl -i 'https://social.duoleads.com/v1/hackernews/thread?id=27326961&limit=10'
- curl -i 'https://social.duoleads.com/v1/social/mentions?q=open+source&days=7'
- curl -i 'https://social.duoleads.com/v1/x/search?q=open+source'
- curl -i 'https://social.duoleads.com/v1/x/posts?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/x/profile?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/reddit/search?q=open+source'
- curl -i 'https://social.duoleads.com/v1/reddit/comments?post=bpvaau'
- curl -i 'https://social.duoleads.com/v1/tiktok/videos?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/tiktok/search?q=open+source'
- curl -i 'https://social.duoleads.com/v1/instagram/profile?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/youtube/transcript?video=iG9CE55wbtY'
- curl -i 'https://social.duoleads.com/v1/youtube/comments?video=iG9CE55wbtY'
- curl -i 'https://social.duoleads.com/v1/threads/posts?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/facebook/ads?q=running+shoes'
- curl -i 'https://social.duoleads.com/v1/social/search?q=open+source&platforms=reddit%2Ctiktok'
- curl -i 'https://social.duoleads.com/v1/social/audience?platform=tiktok&handle=nasa'
- curl -i 'https://social.duoleads.com/v1/social/accounts?platform=tiktok&q=nasa'
- curl -i 'https://social.duoleads.com/v1/linkedin/company?url=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Fmicrosoft%2F'
- curl -i 'https://social.duoleads.com/v1/social/people?platform=tiktok&q=open+source'
- curl -i 'https://social.duoleads.com/v1/tiktok/followers?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/tiktok/following?handle=nasa'
- curl -i 'https://social.duoleads.com/v1/linkedin/profile?url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fsynthetic-person%2F'

## Machine-readable

- [OpenAPI 3.1](https://social.duoleads.com/openapi.json): request and response schemas
- [Agent skill](https://social.duoleads.com/skill.md): when to call which route
- [MCP endpoint](https://social.duoleads.com/mcp): Streamable HTTP; tools/list is free, tools/call is paid
- [A2A agent card](https://social.duoleads.com/.well-known/agent-card.json): JSON-RPC at https://social.duoleads.com/a2a; a message without a skill is free, skill calls are paid with the a2a-x402 extension
- [x402 resource index](https://social.duoleads.com/.well-known/x402): every paid resource URL

## Legal

- [Terms](https://social.duoleads.com/terms) and [privacy](https://social.duoleads.com/privacy)

## Disclaimer

Public data via third-party providers; not affiliated with or endorsed by any platform. Do not use to profile, target or train AI on individuals. Third-party data, provided as is: it may be delayed, incomplete or wrong. Terms: https://social.duoleads.com/terms