threads-rs

Rust client library for the Meta Threads API.

Rust port of threads-go.

Features

• Full Threads API coverage: posts, replies, insights, user profiles, search, and location tagging
• OAuth 2.0 authentication with short-lived and long-lived token exchange
• Automatic rate limiting and retry with exponential backoff
• Cursor-based pagination helpers
• Strongly typed request/response models
• Pluggable token storage

Requirements

• Rust 1.85+
• A Meta Threads API app with client ID, secret, and redirect URI

Installation

Add to your Cargo.toml:

[dependencies]
threads-rs = { git = "https://github.com/tirthpatell/threads-rs" }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick start

use threads_rs::client::{Config, Client};

#[tokio::main]
async fn main() -> threads_rs::Result<()> {
    let config = Config::new("client-id", "client-secret", "https://example.com/cb");
    let client = Client::with_token(config, "YOUR_ACCESS_TOKEN").await?;

    let me = client.get_me().await?;
    println!("Logged in as @{}", me.username);

    Ok(())
}

Authentication

The library supports the full Threads OAuth 2.0 flow:

use threads_rs::client::{Config, Client};

# async fn run() -> threads_rs::Result<()> {
let config = Config::new("client-id", "client-secret", "https://example.com/cb");
let client = Client::new(config).await?;

// 1. Generate the authorization URL
let (auth_url, state) = client.get_auth_url(&[]);
// Redirect user to auth_url, verify state on callback

// 2. Exchange the authorization code for a short-lived token
client.exchange_code_for_token("AUTH_CODE").await?;

// 3. Convert to a long-lived token (60 days)
client.get_long_lived_token().await?;

// 4. Refresh before expiry
client.refresh_token().await?;
# Ok(())
# }

You can also create a client from environment variables:

# async fn run() -> threads_rs::Result<()> {
// Reads THREADS_CLIENT_ID, THREADS_CLIENT_SECRET, THREADS_REDIRECT_URI
let client = threads_rs::client::Client::from_env().await?;
# Ok(())
# }

API coverage

Posts

Replies

Users

Insights

Search & Location

Pagination

Built-in iterators for paginated endpoints:

use threads_rs::client::{Config, Client};
use threads_rs::pagination::PostIterator;
use threads_rs::types::ids::UserId;

# async fn run() -> threads_rs::Result<()> {
# let config = Config::new("id", "secret", "https://example.com/cb");
# let client = Client::with_token(config, "TOKEN").await?;
let user_id = UserId::from("me");
let mut iter = PostIterator::new(&client, user_id, None);

while let Some(page) = iter.next().await? {
    for post in &page.data {
        println!("{}: {}", post.id, post.text.as_deref().unwrap_or(""));
    }
}
# Ok(())
# }

ReplyIterator and SearchIterator work the same way.

Configuration

All fields on Config are public and can be customized:

use threads_rs::client::Config;
use std::time::Duration;

let mut config = Config::new("client-id", "client-secret", "https://example.com/cb");
config.http_timeout = Duration::from_secs(60);
config.debug = true;

Environment variable configuration is also supported via Config::from_env():

Error handling

All API methods return threads_rs::Result<T>. Errors are strongly typed:

use threads_rs::Error;

# async fn run(client: &threads_rs::client::Client) {
# let post_id = threads_rs::types::ids::PostId::from("123");
match client.get_post(&post_id).await {
    Ok(post) => println!("{:?}", post),
    Err(Error::Authentication { message, .. }) => eprintln!("Auth failed: {message}"),
    Err(Error::RateLimit { retry_after, .. }) => eprintln!("Rate limited, retry in {retry_after:?}"),
    Err(Error::Validation { field, message, .. }) => eprintln!("Invalid {field}: {message}"),
    Err(e) => eprintln!("Error: {e}"),
}
# }

License

MIT