Unofficial Python client for Meta Threads.net API
Project description
Meta's Threads.net API
Unofficial, Reverse-Engineered Python client for Meta's Threads.
Inspired by NPM Threads-API
Threads API - Python
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 incached_token_path
.
Table of content:
Demo
Getting Started
📦 Installation
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())
Customize HTTP Client
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)
Set Desired Log Level
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
Example 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 ---->
Troubleshooting threads-api
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
)
Supported Features
- ✅ 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
Usage Examples
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.
📌 Roadmap
- 🚧 Share a video
- 🚧 Documentation Improvements
- 🚧 Add coverage Pytest + Coverage Widget to README
Contributing to Danie1/threads-api
Getting Started
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
License
This project is licensed under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file threads-api-1.2.0.tar.gz
.
File metadata
- Download URL: threads-api-1.2.0.tar.gz
- Upload date:
- Size: 24.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f4a9db9fd203a098f04b003a8488af7b28ff13fe15b78af50a7f29ffcc834293 |
|
MD5 | 92ff291fc6d6cd1f4f956c2db8b569d5 |
|
BLAKE2b-256 | 1cded97d334fd393cf4572d5aed1fb99aeb9c3962aaf4f59e1ac30e263fd10c4 |
File details
Details for the file threads_api-1.2.0-py3-none-any.whl
.
File metadata
- Download URL: threads_api-1.2.0-py3-none-any.whl
- Upload date:
- Size: 23.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.6
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9dfec0c44592a1dae9f9cb7df5ff37062e13074c27cee2cd57cb1687183f25d |
|
MD5 | b8d9bbb322bbe205811f2929fec13a89 |
|
BLAKE2b-256 | b06ad06e70ea82fd7f0d1fe0b43556550a3a07dbf268792d23ebfb85e6126d0e |