social-dataFetch real-time social media data from X (Twitter) and Reddit by keyword, username, date range, and filters with engagement metrics via Macrocosmos SN13 API.
Install via ClawdBot CLI:
clawdbot install Arrmlet/social-dataFetch real-time social media data from X (Twitter) and Reddit by keyword, username, date range, and filters with engagement metrics via Macrocosmos SN13 API on Bittensor.
| Variable | Required | Type | Description |
|----------|----------|------|-------------|
| MC_API | Yes | secret | Macrocosmos API key. Required for all API requests. Get your free key at https://app.macrocosmos.ai/account?tab=api-keys |
Setup: The MC_API key must be set as an environment variable. It is passed as a Bearer token in the Authorization header for REST calls, or provided directly to the Python SDK client.
POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandDataContent-Type: application/json
Authorization: Bearer <YOUR_MC_API_KEY>{
"source": "X",
"usernames": ["@elonmusk"],
"keywords": ["AI", "bittensor"],
"start_date": "2026-01-01",
"end_date": "2026-02-10",
"limit": 10,
"keyword_mode": "any"
}| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| source | string | Yes | "X" or "REDDIT" (case-sensitive) |
| usernames | array | No | Up to 5 usernames. @ optional. X only (not available for Reddit) |
| keywords | array | No | Up to 5 keywords/hashtags. For Reddit: use subreddit format "r/subreddit" |
| start_date | string | No | YYYY-MM-DD or ISO format. Defaults to 24h ago |
| end_date | string | No | YYYY-MM-DD or ISO format. Defaults to now |
| limit | int | No | 1-1000 results. Default: 10 |
| keyword_mode | string | No | "any" (default) matches ANY keyword, "all" requires ALL keywords |
{
"data": [
{
"datetime": "2026-02-10T17:30:58Z",
"source": "x",
"text": "Tweet content here",
"uri": "https://x.com/username/status/123456",
"user": {
"username": "example_user",
"display_name": "Example User",
"followers_count": 1500,
"following_count": 300,
"user_description": "Bio text",
"user_blue_verified": true,
"profile_image_url": "https://pbs.twimg.com/..."
},
"tweet": {
"id": "123456",
"like_count": 42,
"retweet_count": 10,
"reply_count": 5,
"quote_count": 2,
"view_count": 5000,
"bookmark_count": 3,
"hashtags": ["#AI", "#bittensor"],
"language": "en",
"is_reply": false,
"is_quote": false,
"conversation_id": "123456"
}
}
]
}curl -s -X POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"source": "X",
"keywords": ["bittensor"],
"start_date": "2026-01-01",
"limit": 10
}'curl -s -X POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"source": "X",
"usernames": ["@MacrocosmosAI"],
"start_date": "2026-01-01",
"limit": 10
}'curl -s -X POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"source": "X",
"keywords": ["chutes", "bittensor"],
"keyword_mode": "all",
"start_date": "2026-01-01",
"limit": 20
}'curl -s -X POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"source": "REDDIT",
"keywords": ["r/MachineLearning", "transformers"],
"start_date": "2026-02-01",
"limit": 50
}'curl -s -X POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"source": "X",
"usernames": ["@opentensor"],
"keywords": ["subnet"],
"start_date": "2026-01-01",
"limit": 20
}'macrocosmos SDKimport asyncio
import macrocosmos as mc
async def search_tweets():
client = mc.AsyncSn13Client(api_key="YOUR_API_KEY")
response = await client.sn13.OnDemandData(
source="X",
keywords=["bittensor"],
usernames=[],
start_date="2026-01-01",
end_date=None,
limit=10,
keyword_mode="any",
)
if hasattr(response, "model_dump"):
data = response.model_dump()
for tweet in data["data"]:
print(f"@{tweet['user']['username']}: {tweet['text'][:100]}")
print(f" Likes: {tweet['tweet']['like_count']} | Views: {tweet['tweet']['view_count']}")
asyncio.run(search_tweets())requests (REST)import requests
url = "https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
payload = {
"source": "X",
"keywords": ["bittensor"],
"start_date": "2026-01-01",
"limit": 10
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
for tweet in data["data"]:
print(f"@{tweet['user']['username']}: {tweet['text'][:100]}")start_date further back (e.g., weeks/months) improves resultskeyword_mode: "all": Great for finding intersection of two topics (e.g., "chutes" AND "bittensor")start_date far back helpsstart_date: Defaults to last 24h which can miss data; set explicitly for best resultsstart_date — don't rely on the 24h default. Use at least 7 days back for user queriesstart_date set weeks/months backkeyword_mode: "all" when combining a topic with a subtopic (e.g., "bittensor" + "chutes")view_count, like_count, retweet_count help rank relevanceis_reply and is_quote — filter for original tweets vs replies depending on use caseFor datasets larger than 1000 results, use the Gravity endpoints:
POST /gravity.v1.GravityService/CreateGravityTask{
"gravity_tasks": [
{"platform": "x", "topic": "#bittensor", "keyword": "dTAO"}
],
"name": "Bittensor dTAO Collection"
}Note: X topics MUST start with # or $. Reddit topics use subreddit format.
POST /gravity.v1.GravityService/GetGravityTasks{
"gravity_task_id": "multicrawler-xxxx-xxxx",
"include_crawlers": true
}POST /gravity.v1.GravityService/BuildDataset{
"crawler_id": "crawler-0-multicrawler-xxxx",
"max_rows": 10000
}Warning: Building stops the crawler permanently.
POST /gravity.v1.GravityService/GetDataset{
"dataset_id": "dataset-xxxx-xxxx"
}Returns Parquet file download URLs when complete.
Quick Query (< 1000 results):
OnDemandData → instant results
Large Collection (7-day crawl):
CreateGravityTask → GetGravityTasks (monitor) → BuildDataset → GetDataset (download)| Error | Cause | Fix |
|-------|-------|-----|
| 401 Unauthorized | Missing or invalid API key | Check Authorization: Bearer header |
| 500 Internal Server Error | Server-side issue (often auth via gRPC) | Verify API key, retry |
| DEADLINE_EXCEEDED | Query timeout — miners can't fulfill request | Use broader date range, switch to keyword search |
| Empty data array | No matching results | Broaden search terms or date range |
Generated Feb 23, 2026
Marketing teams can track mentions of their brand, products, or competitors on X and Reddit in real-time. This enables quick response to customer feedback, identification of trending topics, and measurement of campaign effectiveness through engagement metrics like likes, retweets, and views.
Analysts can gather social media data by keywords or subreddits to identify emerging trends, consumer preferences, and market shifts. This supports data-driven decisions for product development, content strategy, and investment opportunities, especially in fast-moving sectors like technology or finance.
Agencies can monitor specific usernames on X to track influencer activity, measure audience engagement, and assess partnership potential. For Reddit, they can analyze discussions in subreddits to understand community sentiment and tailor outreach efforts for better engagement.
Organizations can set up keyword alerts for negative mentions or emerging issues on social platforms. By filtering data with date ranges and engagement metrics, they can quickly detect potential crises, assess their impact, and coordinate timely responses to mitigate reputational damage.
Media companies or content creators can fetch posts from specific users or keywords to curate relevant news, memes, or discussions. This helps in building automated feeds, generating insights for articles, or creating summaries for audiences interested in niche topics like AI or cryptocurrencies.
Offer tiered subscription plans based on API call volume, data limits, or advanced features like historical data access. Customers pay monthly or annually for access to real-time social media data, with premium tiers including higher limits and priority support.
Develop a custom dashboard that integrates the Macrocosmos API to provide branded analytics tools for clients. Charge setup fees and ongoing licensing costs, allowing businesses to monitor social metrics without building their own infrastructure from scratch.
Aggregate and anonymize social data into industry-specific reports or datasets, then sell them to market research firms, academic institutions, or investors. This model leverages bulk data collection to create value-added products with minimal per-query costs.
💬 Integration Tip
Start by setting the MC_API environment variable securely, then use the provided curl or Python examples to test basic keyword searches before scaling to complex filters.
Fetch and read transcripts from YouTube videos. Use when you need to summarize a video, answer questions about its content, or extract information from it.
Fetch and summarize YouTube video transcripts. Use when asked to summarize, transcribe, or extract content from YouTube videos. Handles transcript fetching via residential IP proxy to bypass YouTube's cloud IP blocks.
Browse, search, post, and moderate Reddit. Read-only works without auth; posting/moderation requires OAuth setup.
Interact with Twitter/X — read tweets, search, post, like, retweet, and manage your timeline.
LinkedIn automation via browser relay or cookies for messaging, profile viewing, and network actions.
Search YouTube videos, get channel info, fetch video details and transcripts using YouTube Data API v3 via MCP server or yt-dlp fallback.