M

Macrocosmos

social-data

Fetch real-time social media data from X (Twitter) and Reddit by keyword, username, date range, and filters with engagement metrics via Macrocosmos SN13 API.

数据来源：ClawHub。在 ClawSkills 查看

607下载量

2收藏数

0浏览量

安装

选择你使用的 Agent

方法一：命令行安装（推荐）

关于 Macrocosmos

Macrocosmos SN13 API - Social Media Data Skill

Fetch 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.

Metadata

name: macrocosmos-social-data
version: 1.0.1
homepage: https://github.com/macrocosm-os/macrocosmos-mcp
source: https://github.com/macrocosm-os/macrocosmos-mcp
pypi: https://pypi.org/project/macrocosmos-mcp
subnet: Bittensor SN13 (Data Universe)
author: Macrocosmos AI
license: MIT

Required Environment Variables

| 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.

---

API Endpoint

POST https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData

Headers

Content-Type: application/json
Authorization: Bearer <YOUR_MC_API_KEY>

---

Request Format

{
  "source": "X",
  "usernames": ["@elonmusk"],
  "keywords": ["AI", "bittensor"],
  "start_date": "2026-01-01",
  "end_date": "2026-02-10",
  "limit": 10,
  "keyword_mode": "any"
}

Parameters

| 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 |

---

Response Format

{
  "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 Examples

1. Keyword Search on X

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
  }'

2. Fetch Tweets from a Specific User

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
  }'

3. Multi-Keyword AND Search

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
  }'

4. Reddit Search

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
  }'

5. User + Keyword Filter

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
  }'

---

Python Examples

Using the `macrocosmos` SDK

import 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())

Using `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]}")

---

Tips & Known Behaviors

What works reliably

High-volume keyword searches: Popular terms like "bittensor", "AI", "iran", "lfg" return fast
Wider date ranges: Setting start_date further back (e.g., weeks/months) improves results
keyword_mode: "all": Great for finding intersection of two topics (e.g., "chutes" AND "bittensor")

What can be flaky

Username-only queries: Can timeout (DEADLINE_EXCEEDED). Adding start_date far back helps
Niche/low-volume keywords: Very specific terms may timeout if miners don't have data indexed
No start_date: Defaults to last 24h which can miss data; set explicitly for best results

Best practices for LLM agents

Always set start_date — don't rely on the 24h default. Use at least 7 days back for user queries
Prefer keywords over usernames — keyword searches are more reliable
For username queries, always include start_date set weeks/months back
Use keyword_mode: "all" when combining a topic with a subtopic (e.g., "bittensor" + "chutes")
Handle timeouts gracefully — if a query times out, retry with broader date range or switch to keyword search
Parse engagement metrics — view_count, like_count, retweet_count help rank relevance
Check is_reply and is_quote — filter for original tweets vs replies depending on use case

---

Gravity API (Large-Scale Collection)

For datasets larger than 1000 results, use the Gravity endpoints:

Create Task

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.

...

Prompt 示例

安装 Macrocosmos 后，可以对 AI 说这些话来触发它

U

Help me get started with Macrocosmos

A

Explains what Macrocosmos does, walks through the setup, and runs a quick demo based on your current project

U

Use Macrocosmos to fetch real-time social media data from X (Twitter) and Reddit by ke...

A

Invokes Macrocosmos with the right parameters and returns the result directly in the conversation

U

What can I do with Macrocosmos in my marketing & growth workflow?

A

Lists the top use cases for Macrocosmos, with example commands for each scenario

常见问题

如何安装 Macrocosmos？▾

将技能文件夹放到 ~/.claude/skills/social-data/ 目录（个人级，所有项目可用），或 .claude/skills/social-data/（项目级）。重启 AI 客户端后，用 /social-data 主动调用，或让 AI 根据上下文自动发现并使用。

Macrocosmos 支持哪些 AI 平台？▾

Macrocosmos 支持 Claude、Cursor、OpenClaw，可与这些 AI 平台无缝集成，扩展其能力。

Macrocosmos 是免费的吗？▾

Macrocosmos 可免费安装使用。请查阅仓库了解许可证信息。

Macrocosmos 有什么功能？▾

Fetch real-time social media data from X (Twitter) and Reddit by keyword, username, date range, and filters with engagement metrics via Macrocosmos SN13 API.

Macrocosmos 属于哪个分类？▾

Macrocosmos 属于「Marketing & Growth」分类，该分类的技能帮助 AI 智能体在此领域执行专业任务。

使用场景

Getting Started with Macrocosmos→Automate Marketing & Growth Workflows with Macrocosmos→Team Collaboration with Macrocosmos→

Macrocosmos

安装

关于 Macrocosmos

Macrocosmos SN13 API - Social Media Data Skill

Metadata

Required Environment Variables

API Endpoint

Headers

Request Format

Parameters

Response Format

curl Examples

1. Keyword Search on X

2. Fetch Tweets from a Specific User

3. Multi-Keyword AND Search

4. Reddit Search

5. User + Keyword Filter

Python Examples

Using the `macrocosmos` SDK

Using `requests` (REST)

Tips & Known Behaviors

What works reliably

What can be flaky

Best practices for LLM agents

Gravity API (Large-Scale Collection)

Create Task

Prompt 示例

常见问题

使用场景

同类技能推荐

AdMapix

API Gateway

Mcporter

Discord

Macrocosmos

安装

关于 Macrocosmos

Macrocosmos SN13 API - Social Media Data Skill

Metadata

Required Environment Variables

API Endpoint

Headers

Request Format

Parameters

Response Format

curl Examples

1. Keyword Search on X

2. Fetch Tweets from a Specific User

3. Multi-Keyword AND Search

4. Reddit Search

5. User + Keyword Filter

Python Examples

Using the macrocosmos SDK

Using requests (REST)

Tips & Known Behaviors

What works reliably

What can be flaky

Best practices for LLM agents

Gravity API (Large-Scale Collection)

Create Task

Prompt 示例

常见问题

使用场景

同类技能推荐

AdMapix

API Gateway

Mcporter

Discord

Using the `macrocosmos` SDK

Using `requests` (REST)