Languages: English | 中文

A powerful and reliable Apify Actor for scraping Threads (threads.com) - Meta's text-based social media platform. Extract posts, profiles, hashtags, and replies. Export to JSON/CSV/Excel.

Threads data scraping has inherent limitations:

• Data Volume Limits: Threads platform restricts accessible data volume. Actual results vary based on account activity, content type, and other factors
• Dynamic Loading: Threads uses infinite scroll to load content, but stops loading after a certain amount
• Rate Limiting: Excessive requests may trigger platform protection mechanisms
• Content Availability: Cannot access private accounts, deleted content, or region-restricted content
• Login Walls: Threads may occasionally display login walls that block scraping

1. Small Batch Testing: Start with smaller limits for initial tests, gradually increase to find optimal settings
2. Realistic Expectations: Understand that actual results may be fewer than requested
3. Error Handling: Be prepared to handle partial failures or incomplete results
4. Execution Intervals: Avoid overly frequent scraping; recommend at least 5-10 minute intervals
5. Data Validation: Always verify that scraped data is complete and accurate
6. Backup Plans: For critical data, consider multiple scraping attempts or different parameters

• Profile Scraping: Fetch user profile data including bio, follower count, verification status, and recent posts (no login required)
• Single Post Extraction: Extract detailed data from a specific post by URL, including replies (no login required)
• Search Posts: Search for posts by keyword with sorting options (currently works without login in our latest smoke tests)
• Hashtag Search: Search posts by hashtag tag (currently works without login in our latest smoke tests)
• Batch Mode: Process multiple keywords/usernames/tags/URLs in one run with concurrency control
• Media Extraction: Capture image and video URLs from posts
• Export Formats: JSON, CSV, Excel

• npm test: unit tests and fixture-based parser integration tests
• npm run smoke:live: live smoke tests for profile, post, search, and hashtag actions against public Threads pages
• npm run smoke:auth: authenticated profile smoke test for auth-only fields such as location and joinedDate

For npm run smoke:auth, provide one of:

• THREADS_STORAGE_STATE_PATH=/path/to/storageState.json
• THREADS_STORAGE_STATE_JSON='{"cookies":[...],"origins":[...]}'

Enable cookie injection for extended data access. Useful when encountering login walls or when you need auth-only profile fields.

How to obtain storageState:

1. Login to Threads in your browser
2. Use Playwright to export storage state:

   // After logging in with Playwright
   await context.storageState({ path: 'storageState.json' });

3. Copy the JSON content to the storageState field

Note: If useCookies is enabled but storageState is empty, the Actor falls back to no-auth mode with a warning. Only cookies and localStorage for Threads domains are injected; sessionStorage is not supported.

Configure rate limit protection to avoid being blocked by Threads.

Example:

{
    "action": "search",
    "keyword": "AI",
    "rateLimitConfig": {
        "requestDelay": 2000,
        "maxRetries": 5,
        "backoffDelay": 10000
    }
}

How it works:

• When Threads returns a rate limit error, the Actor automatically pauses and retries
• Uses exponential backoff: first retry after 5s, second after 10s, third after 20s (with default settings)
• Logs warnings when rate limited to help you monitor and adjust settings

Fetch user profile data and recent posts.

{
    "action": "profile",
    "username": "zuck",
    "maxItems": 20
}

Extract detailed data from a specific post including replies.

{
    "action": "post",
    "postUrl": "https://www.threads.com/@zuck/post/ABC123xyz",
    "maxItems": 50
}

Current behavior: In our latest live smoke tests, Threads search worked without login. Keep useCookies and storageState available as a fallback for login walls or rate-limit changes.

Search for posts by keyword on Threads.

{
    "action": "search",
    "keyword": "artificial intelligence",
    "filter": "recent",
    "maxItems": 50,
    "useCookies": true,
    "storageState": { "...your exported storageState..." }
}

Current behavior: In our latest live smoke tests, Threads hashtag search worked without login. Keep useCookies and storageState available as a fallback for login walls or rate-limit changes.

Search posts by hashtag.

{
    "action": "hashtag",
    "tag": "AI",
    "filter": "recent",
    "maxItems": 50,
    "useCookies": true,
    "storageState": { "...your exported storageState..." }
}

Process multiple inputs in one run. concurrency controls how many tasks run in parallel.

{
    "action": "search",
    "keywords": ["vibe coding", "machine learning"],
    "usernames": ["zuck", "openai"],
    "tags": ["AI", "tech"],
    "postUrls": ["https://www.threads.com/@user/post/ABC123"],
    "maxItems": 20,
    "filter": "recent",
    "concurrency": 2
}

Each post is stored as a separate record:

{
    "id": "ABC123xyz",
    "url": "https://www.threads.com/@johndoe/post/ABC123xyz",
    "author": {
        "username": "johndoe",
        "displayName": "John Doe",
        "profileUrl": "https://www.threads.com/@johndoe",
        "avatarUrl": "https://...",
        "isVerified": false
    },
    "content": "This is the post content about AI and technology...",
    "timestamp": "2025-12-04T10:14:34.000Z",
    "stats": {
        "likes": 142,
        "replies": 23,
        "reposts": 8,
        "shares": 5
    },
    "images": ["https://..."],
    "videos": ["https://..."],
    "links": ["https://example.com"],
    "quotedPost": null,
    "source": "search",
    "parentId": null
}

{
    "username": "zuck",
    "displayName": "Mark Zuckerberg",
    "profileUrl": "https://www.threads.com/@zuck",
    "avatarUrl": "https://...",
    "bio": "Building the future...",
    "isVerified": true,
    "followersCount": 5417000,
    "location": "California, USA",
    "joinedDate": "July 2023",
    "partial": false,
    "missingFields": [],
    "type": "profile",
    "source": "profile"
}

Note: location and joinedDate require authentication. Enable useCookies and provide storageState to access these fields. Without login, these fields will be null. See Authentication for setup instructions.

Note: Recent posts from the profile page are pushed as separate Dataset items with source: "profile_posts" and profile: <username>.

• Posts: Entries missing essential data (content, author, or valid timestamp) are filtered out and not written to the Dataset
• Profiles: If optional fields are missing (e.g., bio/avatar/followers), the record is kept but marked with partial: true and missingFields
• Replies and profile posts: Reuse the same validation; invalid ones are skipped

# Install dependencies
npm install

# Lint source and tests
npm run lint

# Build TypeScript output
npm run build

# Run unit tests
npm test

Current automated tests cover:

• post URL normalization and post ID extraction
• selector utility behavior
• post/profile validation rules
• relative time and stat number parsing
• fixture-based parser integration tests for search results, single posts, and profile pages

They do not yet cover live Threads scraping flows.

• Social Media Monitoring: Track brand mentions and conversations
• Influencer Discovery: Find content creators by follower metrics
• Competitor Research: Monitor competitor activity and engagement
• Content Analysis: Analyze trending topics and hashtags
• Lead Generation: Discover profiles in your niche
• Market Research: Understand audience sentiment

Post Limits:

• User posts: Only recent posts accessible, quantity varies by account
• Keyword search: Limited by Threads search results
• Profile search: Limited by search results

Note: Threads dynamically loads content, which may limit the amount of data retrievable through scrolling. Actual results may be fewer than the requested limit.

Q: Why do I get fewer results than my maxItems limit? A: Threads limits the amount of content accessible through its interface. The actual number of available posts varies based on multiple factors including account activity, content type, etc.

Q: Can I scrape private accounts? A: No. This Actor only scrapes publicly available data. Private accounts, deleted content, and region-restricted content cannot be accessed.

Q: Why do some posts have truncated text? A: Threads displays truncated content in feeds. Use the post URL via HTTP request tools to get full content.

Q: Are usernames with dots supported? A: Yes. Usernames like @user.name are fully supported.

Q: How do I handle rate limiting? A: Use Apify Proxy (recommended), reduce concurrency, and add intervals between runs. If you encounter persistent issues, wait 10-15 minutes before retrying.

Q: What happens if Threads shows a login wall? A: The Actor will log an error and skip that request. Consider using different proxy settings or reducing request frequency.

Q: Can I get engagement metrics? A: Yes. The Actor extracts likes, replies, reposts, and shares for each post to help you analyze content performance.

Important: This Actor operates without login, meaning accessible data volume is limited by Threads' public interface.

If you need to scrape your own account's data, consider using the Official Threads API:

• More reliable and stable
• Higher rate limits
• Access to full post history
• No risk of being blocked
• Official support from Meta

The Threads API is the recommended method for accessing your own account data or for large-scale, production-level data extraction needs.

Have questions or issues?

• Check Apify Documentation
• View all fields in the dataset for complete data
• Report issues via the Issues tab
• Contact support through the Apify platform

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

This tool is for educational and research purposes only. Please use responsibly and comply with Threads' Terms of Service. The developers are not responsible for any misuse of this tool or violations of platform policies.

Keywords: Threads scraper, Threads API, Meta Threads, social media scraper, Instagram Threads, Threads posts, Threads data extraction, social media monitoring, Threads automation, influencer discovery, follower count scraper