PRESERVED.md

threads-py

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

Looking for the TypeScript version? Check out junhoyeo/threads-api.

---

Installation

pip install --no-cache-dir --upgrade threads-py

Initialization

Public Data Usage:

from threadspy import ThreadsAPI
api = ThreadsAPI()

Private Data Usage:

from threadspy import ThreadsAPI
api = ThreadsAPI(
      username="Your-Username"
      password="Your-Password"
      token="You-Token" # optional (if you're already authenticated)
    )

---

Implementation Roadmap and Methodology Overview

• 📢 Read public data
  • ✅ Fetch User ID
  • ✅ Read User Profile Info
  • ✅ Read list of User Threads
    • 🚧 With Pagination (If auth provided)
  • ✅ Read list of User Replies
    • 🚧 With Pagination (If auth provided)
  • ✅ Fetch Post ID
  • ✅ Read A Single Thread
  • ✅ Get Thread Likes
• 🔏 Read user private data
  • ✅ Read User Followings
  • ✅ Read User Followers
  • ✅ Get suggested users
  • ✅ Search Query
  • ✅ Read User Timeline Feed
  • ✅ Get Notifications
• 🔏 Write Private Data (Authentication Required)
  • ✅ Create New Thrad Or Reply To Eexisting Thread
    • 🚧 Make link previews to get shown
  • ✅ Delete Thread
  • 🚧 Quote Thread
• 🔒 Friendship Actions
  • ✅ Follow User
  • ✅ Unfollow User
  • ✅ Block User
  • ✅ Unblock User
  • ✅ Mute User
  • ✅ Unmute User
  • ✅ Restrict User
  • ✅ Unrestrict User
  • ✅ Check Friendship Status With Another Users
• 🔒 Interactions (Authentication Required)
  • ✅ Like Thread
  • ✅ Remove Like From Thread
  • ✅ Repost Thread
  • ✅ Delete Reposted Thread
• 🚧 LangChain Agent (threadspy.ai)
  • 🚧 Threads Tool for LangChain
  • 📌 Link Threads & LLaMa (@Mineru98)
  • 📌 Provide statistical analysis of posts in Threads (@Mineru98)

---

Read public data

Fetch User ID:

user_id = api.get_user_id_from_username(username)

Parameters

Parameters	Description	Type	Required
username	Target username	String	Yes

Read User Profile Info:

user_profile = api.get_user_profile(username, user_id)

Parameters

Parameters	Description	Type	Required	Default Value
username	Target username	String	Yes	-
user_id	Target User ID	String	No	None

Read list of User Threads:

user_threads = api.get_user_profile_threads(username, user_id)

Parameters

Parameters	Description	Type	Required	Default Value
username	Target username	String	Yes	-
user_id	Target User ID	String	No	None

Read list of User Replies:

user_replies = api.get_user_profile_replies(username, user_id)

Parameters

Parameters	Description	Type	Required	Default Value
username	Target username	String	Yes	-
user_id	Target User ID	String	No	None

Fetch Post ID:

via Thread ID E.g. "CuW6-7KyXme":

post_id = api.get_post_id_from_thread_id(thread_id)

Parameters

Parameters	Description	Type	Required
thread_id	Last part of the thread URL	String	Yes

Examples

thread_id = 'CugF-EjhQ3r'
post_id = api.get_post_id_from_thread_id(thread_id)

via Post URL E.g."https://www.threads.net/t/CuW6-7KyXme":

post_id = api.get_post_id_from_url(post_url)

Parameters

Parameters	Description	Type	Required
post_url	Thread URL	String	Yes

Examples

post_url = 'https://www.threads.net/t/CugF-EjhQ3r'
post_id = api.get_post_id_from_url(post_url)

Read A Single Thread:

single_thread = api.get_threads(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Target username	String	Yes

Get Thread Likes:

thread_likes = api.get_thread_likers(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Target username	String	Yes

---

Read Private Data

Read User Followings:

user_followers = api.get_followings(user_id)

Parameters

Parameters	Description	Type	Required
user_id	Target User ID	String	Yes

Read User Followers:

user_followings = api.get_followers(user_id)

Parameters

Parameters	Description	Type	Required
user_id	Target User ID	String	Yes

Get Suggested Users:

suggested_users = api.get_suggested_users(count, paging)

Parameters

Parameters	Description	Type	Required	Default Value
count	Number of suggested users	Integer	No	15
paging	Page number	Integer	No	None

Search Query:

thread_likes = api.search(search_parameter)

Parameters

Parameters	Description	Type	Required
search_parameter	Search Query	String	Yes

Read User Timeline Feed:

user_timeline = api.get_timeline(max_id)

Parameters

Parameters	Description	Type	Required
max_id	Next Posts Batch ID	String	No

Get Notifications:

user_timeline = api.get_timeline(max_id)

Parameters

Parameters	Description	Type	Required	Default Value
notification_filter	Next Posts Batch ID	String	No	'replies'
max_id	Next Posts Batch ID	String	No	None
pagination	Next Posts Batch ID	String	No	None

'notification_filter' values: 'mentions', 'replies', 'verified'

---

Write Private Data (Authentication Required)

Create New Thrad Or Reply To Eexisting Thread:

boolean_response = api.publish(count, image_path, url, parent_post_id)

Parameters

Parameters	Description	Type	Required	Default Value
caption	Text to post in Thread	String	Yes	15
image_path	Image Path to post in Thread	String	No	None
url	Link to post in Thread	String	No	None
parent_post_id	Post ID	String	No	None

Examples

• Text Threads:

api.publish(caption="🤖 Hello World!")

• Threads with Image:

api.publish(
  caption= '🤖 Threads with Link Image',
  image_path="https://github.com/junhoyeo/threads-py/raw/main/.github/logo.jpg"
  )

• Threads with Link Attachment:

api.publish(
  caption= '🤖 Threads with Link Image',
  url="https://github.com/junhoyeo/threads-py"
  )

Reply to Other Threads:

parent_post_url = 'https://www.threads.net/t/CugF-EjhQ3r'
parent_post_id = api.get_post_id_from_url(parent_post_url) # or use `get_post_id_from_thread_id`

api.publish({
  text: '🤖 Beep',
  link: 'https://github.com/junhoyeo/threads-py',
  parent_post_id: parent_post_id,
})

Delete Thread:

boolean_response = api.delete_thread(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Post Identifier	String	Yes

---

Friendship Actions (Authentication Required)

Follow User:

boolean_response = api.follow(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Unfollow User:

boolean_response = api.unfollow(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Block User:

boolean_response = api.block(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Unblock User:

boolean_response = api.unblock(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Mute User:

boolean_response = api.mute(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Unmute User:

boolean_response = api.unmute(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Restrict User:

boolean_response = api.restrict(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Unrestrict User:

boolean_response = api.unrestrict(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

Check Friendship Status With Another Users:

friendship_status = api.friendship_status(user_id)

Parameters

Parameters	Description	Type	Required
user_id	User Identifier	String	Yes

---

Interactions (Authentication Required)

Like Thread:

boolean_response = api.like(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Post Identifier	String	Yes

Remove Like From Thread:

boolean_response = api.unlike(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Post Identifier	String	Yes

Repost Thread:

boolean_response = api.repost_thread(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Post Identifier	String	Yes

Delete Reposted Thread:

boolean_response = api.unrepost_thread(post_id)

Parameters

Parameters	Description	Type	Required
post_id	Post Identifier	String	Yes

---

Contributors

Junho Yeo 💻

iamiks 💻

DrunkLeen 💻

Asharaf Ali 💻

mirageoasis 💻

License

MIT © Junho Yeo

If you find this project intriguing, please consider starring it(⭐) or following me on GitHub (I wouldn't say Threads).