Fetch real-time social media data from X (Twitter) and Reddit through the Macrocosmos SN13 network. IMPORTANT: This tool requires 'source' parameter to be either 'X' or 'REDDIT' (case-sensitive). Parameters:

• source (str, REQUIRED): Data platform - must be 'X' or 'REDDIT'

• usernames (List[str], optional): Up to 5 usernames to monitor.

  • For X: '@' symbol is optional (e.g., ['elonmusk', '@spacex'] both work)

  • NOT available for Reddit

• keywords (List[str], optional): Up to 5 keywords/hashtags to search

  • For X: any keywords or hashtags (e.g., ['AI', 'crypto', '#bitcoin'])

  • For Reddit: subreddit names (e.g., ['r/astronomy', 'space']) or 'r/all' for all subreddits

• start_date (str, optional): Start date/datetime in YYYY-MM-DD or ISO format

  • Examples: '2024-04-01' or '2024-01-01T00:00:00Z'

  • Defaults to 24 hours ago from current time if not specified

• end_date (str, optional): End date/datetime in YYYY-MM-DD or ISO format

  • Examples: '2024-04-25' or '2024-06-03T23:59:59Z'

  • Defaults to current time if not specified

• limit (int, optional): Maximum number of results to return (range: 1-1000, default: 10)

• keyword_mode (str, optional): How to match keywords - 'any' (default) or 'all'

  • 'any': returns posts matching ANY of the keywords

  • 'all': returns posts matching ALL of the keywords Default Behavior (when dates not specified): The tool searches the last 24 hours (from current time back to 24 hours ago). Usage Examples:

1. Get recent tweets from specific users: query_on_demand_data(source='X', usernames=['@elonmusk', '@spacex'], limit=20)

2. Search tweets by keywords in last 24 hours: query_on_demand_data(source='X', keywords=['AI', 'machine learning'], limit=30)

3. Monitor specific users AND filter by keywords: query_on_demand_data(source='X', usernames=['@nasa'], keywords=['space', 'mars'], limit=20)

4. Monitor Reddit subreddits: query_on_demand_data(source='REDDIT', keywords=['r/astronomy', 'space'], limit=50)

5. Search across all of Reddit with date range: query_on_demand_data(source='REDDIT', keywords=['r/all', 'space'], start_date='2025-04-01', end_date='2025-04-02', limit=50)

6. Strict keyword matching (requires ALL keywords): query_on_demand_data(source='X', keywords=['AI', 'machine learning'], keyword_mode='all', limit=30)

7. Precise datetime range search: query_on_demand_data(source='X', keywords=['Bitcoin'], start_date='2024-06-01T00:00:00Z', end_date='2024-06-03T23:59:59Z', limit=100)

Returns: JSON object containing:

• status: "success" or error information

• data: Array of posts/tweets with full content, user information, engagement metrics, timestamps, platform-specific metadata, and media attachments

• meta: Processing statistics (miners queried, response rates, items returned, etc.) Platform-Specific Notes:

• X (Twitter): '@' symbol is optional for usernames

• Reddit: Does NOT support username filtering, only subreddit/keyword searches

• All timestamps returned in UTC format

Create a Gravity task for large-scale data collection from X (Twitter) or Reddit. Use this for collecting large datasets over time (up to 7 days). For quick queries (up to 1000 results), use query_on_demand_data instead.

The task registers on the network within 20 minutes and collects data for 7 days. You'll receive an email notification when the dataset is ready for download.

Parameters:

• tasks (List[dict], REQUIRED): List of task objects, each containing:

  • platform (str): 'x' or 'reddit'

  • topic (str): The hashtag/subreddit to monitor

    • For X: MUST start with '#' or '$' (e.g., '#ai', '$BTC') - plain keywords are rejected!

    • For Reddit: subreddit name (e.g., 'r/MachineLearning')

  • keyword (str, optional): Additional keyword filter within the topic

    • Filters posts to only those containing this keyword

    • Example: topic='#Bittensor', keyword='dTAO' -> only #Bittensor posts mentioning 'dTAO'

• name (str, optional): Name for the task (helps organize multiple tasks)

• email (str, optional): Email address for notification when dataset is ready

• redirect_url (str, optional): URL to redirect to from the email notification

Returns:

• gravity_task_id: Unique identifier to track and manage the task

Examples:

1. Basic collection: create_gravity_task( tasks=[{"platform": "x", "topic": "#ai"}], name="AI Tweets" )

2. With keyword filter: create_gravity_task( tasks=[{"platform": "x", "topic": "#Bittensor", "keyword": "dTAO"}], name="Bittensor dTAO mentions" )

3. Multiple platforms: create_gravity_task( tasks=[ {"platform": "x", "topic": "#ai", "keyword": "LLM"}, {"platform": "reddit", "topic": "r/MachineLearning"} ], name="AI Data Collection", email="user@example.com" )

Get the status of a Gravity task and see how much data has been collected.

Parameters:

• gravity_task_id (str, REQUIRED): The ID of the gravity task to check

• include_crawlers (bool, default: True): Whether to include detailed crawler information Set to True to see records_collected and bytes_collected for each crawler

Returns:

• Task status (Running, Completed, Pending, etc.)

• Task name and start time

• List of crawler IDs (needed for build_dataset)

• When include_crawlers=True: records_collected, bytes_collected per crawler

Example: get_gravity_task_status(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")

Build a dataset from collected data before the 7-day task completion. Use this when you have enough data and don't want to wait for the full collection period.

WARNING: Building a dataset will STOP the crawler and de-register it from the network. The crawler will no longer collect new data after this operation.

Parameters:

• crawler_id (str, REQUIRED): The ID of the crawler to build dataset from (Get this from get_gravity_task_status response - look for 'crawler_ids' field)

• max_rows (int, default: 10000): Maximum number of rows to include in the dataset

• email (str, optional): Email address for notification when dataset is ready

• redirect_url (str, optional): URL to redirect to from the email notification

Returns:

• dataset_id: Unique identifier to track the dataset build

• Build status and progress information (10 steps total)

Example: build_dataset( crawler_id="crawler-0-multicrawler-9f518ae4-xxxx", max_rows=10000, email="user@example.com" )

Get the status of a dataset build and download links when ready.

Parameters:

• dataset_id (str, REQUIRED): The ID of the dataset to check

Returns:

• Build status (Running, Completed, etc.)

• Progress steps (10 total steps)

• When completed: Download URLs for Parquet files

• File metadata (size, row count, expiration date)

Example: get_dataset_status(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")

Cancel a running Gravity task and stop data collection.

Parameters:

• gravity_task_id (str, REQUIRED): The ID of the gravity task to cancel

Returns:

• Success or error message

Example: cancel_gravity_task(gravity_task_id="multicrawler-9f518ae4-xxxx-xxxx-xxxx-8b73d7cd4c49")

Cancel a dataset build or purge a completed dataset.

Parameters:

• dataset_id (str, REQUIRED): The ID of the dataset to cancel/purge

Returns:

• Success or error message

Example: cancel_dataset(dataset_id="dataset-71e97cfa-xxxx-xxxx-xxxx-33cd91be9028")