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 [email protected]: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 [email protected]: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.