Skip to content
This repository has been archived by the owner on Oct 1, 2023. It is now read-only.

Danie1/threads-api

Repository files navigation

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


Meta's Threads.net API

Downdloads Version Releases Python MIT License

Workflow Status

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 in cached_token_path.

Table of content:

Demo

drawing

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
  • ✅ 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 [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

License

This project is licensed under the MIT license.