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_pathfor connections, to reduce the number of actual login attempts. When needed, threads-api will reconnect and update the file incached_token_path.
Table of content:
pip install threads-apior
poetry add threads-apiExample 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=DEBUGExample of Request when 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
- ✅ Read a user_id (eg.
- ✅ 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.pyView 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 shellor
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.txtThis project is licensed under the MIT license.