As of October 1st 2023 this repository is archived, and no longer be maintained.

Unofficial, Reverse-Engineered Python client for Meta's Threads.

Inspired by NPM Threads-API

Threads API is an unofficial Python client for Meta's Threads API. It allows you to interact with the API to login, read and publish posts, view who liked a post, retrieve user profile information, follow/unfollow and much more.

✅ Configurable underlying HTTP Client (aiohttp / requests / instagrapi's client / implement your own)

✅ Authentication Methods supported via instagrapi

✅ Stores token and settings locally, to reduce login-attempts (uses the same token for all authenticated requests for up to 24 hrs)

✅ Pydantic structures for API responses (for IDE auto-completion) (at types.py)

✅ Actively Maintained since Threads.net Release (responsive in Github Issues, try it out!)

Important Tip Use the same cached_token_path for connections, to reduce the number of actual login attempts. When needed, threads-api will reconnect and update the file in cached_token_path.

Table of content:

• Demo
• Getting started
  • Installation
  • Set Log Level & Troubleshooting
  • Set HTTP Client
• Supported Features
• Usage Examples
• Roadmap
• Contributions
• License

pip install threads-api

or

poetry add threads-api

Example using threads-api to post to Threads.net:

from threads_api.src.threads_api import ThreadsAPI import asyncio import os from dotenv import load_dotenv load_dotenv() async def post(): api = ThreadsAPI() await api.login(os.environ.get('INSTAGRAM_USERNAME'), os.environ.get('INSTAGRAM_PASSWORD'), cached_token_path=".token") result = await api.post(caption="Posting this from the Danie1/threads-api!", image_path=".github/logo.jpg") if result: print("Post has been successfully posted") else: print("Unable to post.") await api.close_gracefully() async def main(): await post() # Run the main function asyncio.run(main())

Each HTTP client brings to the table different functionality. Use whichever you like, or implement your own wrapper.

Usage:

api = ThreadsAPI(http_session_class=AioHTTPSession) # default # or api = ThreadsAPI(http_session_class=RequestsSession) # or api = ThreadsAPI(http_session_class=InstagrapiSession)

Threads-API reads the environment variable LOG_LEVEL and sets the log-level according to its value.

Possible values include: DEBUG, INFO, WARNING, ERROR, CRITICAL

Log Level defaults to WARNING when not set.

Useful to know:

# Set Info (Prints general flow) export LOG_LEVEL=INFO

# Set Debug (Prints HTTP Requests + HTTP Responses) export LOG_LEVEL=DEBUG

<---- START ----> Keyword arguments: [title]: ["PUBLIC REQUEST"] [type]: ["GET"] [url]: ["https://www.instagram.com/instagram"] [headers]: [{ "Authority": "www.threads.net", "Accept": "*/*", "Accept-Language": "en-US,en;q=0.9", "Cache-Control": "no-cache", "Content-Type": "application/x-www-form-urlencoded", "Origin": "https://www.threads.net", "Pragma": "no-cache", "Sec-Fetch-Dest": "document", "Sec-Fetch-Mode": "navigate", "Sec-Fetch-Site": "cross-site", "Sec-Fetch-User": "?1", "Upgrade-Insecure-Requests": "1", "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.1.2 Safari/605.1.15", "X-ASBD-ID": "129477", "X-IG-App-ID": "238260118697367" }] <---- END ----> 

Upon unexpected error, or upon receiving an exception with: Oops, this is an error that hasn't yet been properly handled.\nPlease open an issue on Github at https://github.com/Danie1/threads-api.

Please open a Github Issue with all of the information you can provide, which includes the last Request and Response (Set LOG_LEVEL=DEBUG)

• ✅ Pydantic typing API responses at types.py
• ✅ Login functionality, including 2FA 🔒
  • ✅ Cache login token securely (reduce login requests / due to restrictive limits)
  • ✅ Saves settings locally, such as device information and timezone to use along your sessions
• ✅ Read recommended posts from timeline (Requires Login 🔒)
• ✅ Write Posts (Requires Login 🔒)
  • ✅ Posts with just text
  • ✅ Posts and quote another post
  • ✅ Posts with text and an image
  • ✅ Posts with text and multiple images
  • ✅ Posts with text that shares a url
  • ✅ Repost a post
  • ✅ Reply to Posts
• ✅ Perform Actions (Requires Login 🔒)
  • ✅ Like Posts
  • ✅ Unlike Posts
  • ✅ Delete post
  • ✅ Delete repost
  • ✅ Follow User
  • ✅ Unfollow User
  • ✅ Block User
  • ✅ Unblock User
  • ✅ Restrict User
  • ✅ Unrestrict User
  • ✅ Mute User
  • ✅ Unmute User
  • ✅ Search for users
  • ✅ Get Recommended Users
  • ✅ Get Notifications (replies / mentions / verified)
  • ✅ Read a user's followers list
  • ✅ Read a user's following list
• ✅ Read Public Data
  • ✅ Read a user_id (eg. 314216) via username(eg. zuck)
  • ✅ Read a user's profile info
  • ✅ Read list of a user's Threads
  • ✅ Read list of a user's Replies
  • ✅ Read Post and a list of its Replies
  • ✅ View who liked a post
• ✅ CI/CD
  • ✅ GitHub Actions Pipeline
• ✅ HTTP Clients
  • ✅ AioHTTP
  • ✅ Requests
  • ✅ Instagrapi

View examples/public_api_examples.py for Public API code examples.

Run as:

python3 examples/public_api_examples.py

View examples/private_api_examples.py for Private API code examples. (🔒 Requires Authentication 🔒)

Run as:

USERNAME=<Instagram Username> PASSWORD=<Instagram Password> python3 examples/private_api_examples.py 

Note: At the end of the file you will be able to uncomment and run the individual examples with ease.

• 🚧 Share a video
• 🚧 Documentation Improvements
• 🚧 Add coverage Pytest + Coverage Widget to README

With Poetry (Recommended)

# Step 1: Clone the project git clone git@github.com:Danie1/threads-api.git # Step 2: Install dependencies to virtual environment poetry install # Step 3: Activate virtual environment poetry shell

or

Without Poetry

# Step 1: Clone the project git clone git@github.com:Danie1/threads-api.git # Step 2: Create virtual environment python3 -m venv env # Step 3 (Unix/MacOS): Activate virtual environment source env/bin/activate # Unix/MacOS # Step 3 (Windows): Activate virtual environment .\env\Scripts\activate # Windows # Step 4: Install dependencies pip install -r requirements.txt

This project is licensed under the MIT license.