Threads API

A standalone library for fetching data from Threads (threads.net).

Installation

npm install @rosid/threads-api

or

bun add @rosid/threads-api

Usage

import { extractTokens, getUserId, fetchThreadsData, searchPosts } from '@rosid/threads-api';

// Extract LSD token
const { lsd } = await extractTokens('zuck');

// Get user ID (cached)
const userId = await getUserId('zuck');

// Fetch threads from a user's profile
const threads = await fetchThreadsData('zuck');

// Search for posts (with LSD token to avoid rate limits)
const { lsd } = await extractTokens('zuck');
const results = await searchPosts('threads', { lsd });

API

extractTokens(user: string)

Extract LSD token from a Threads profile page.

Returns: Promise<{ lsd: string }>

const { lsd } = await extractTokens('zuck');
// { lsd: "token_value_here" }

getUserId(user: string)

Get user ID from a Threads profile. Results are cached for 1 hour.

Returns: Promise<string>

const userId = await getUserId('zuck');
// "1234567890"

fetchThreadsData(user: string)

Fetch thread items from a user's profile page.

Returns: Promise<ThreadItem[]>

ThreadItem Structure:

interface ThreadItem {
  post: {
    user?: {
      username: string;
      profile_pic_url: string;
    };
    taken_at: number;           // Unix timestamp
    code: string;               // Post code/ID
    caption?: {
      text: string;             // Post text content
    };
    text_post_app_info?: {
      share_info?: {
        quoted_post?: any;      // Quoted post data
        reposted_post?: any;    // Reposted post data
      };
      reply_to_author?: any;   // Reply information
    };
    image_versions2?: any;      // Image media data
    carousel_media?: any;       // Carousel/multiple images
    video_versions?: any;       // Video media data
  };
}

Example:

const threads = await fetchThreadsData('zuck');
// [
//   {
//     post: {
//       user: {
//         username: "zuck",
//         profile_pic_url: "https://..."
//       },
//       taken_at: 1699123456,
//       code: "C1234567890",
//       caption: {
//         text: "Post content here..."
//       },
//       image_versions2: { ... },
//       // ... other media fields
//     }
//   },
//   // ... more threads
// ]

searchPosts(query: string, options?: SearchOptions)

Search for posts on Threads by keyword.

Parameters:

• query: string - Search query/keyword
• options?: SearchOptions - Optional search parameters
  • serp_type?: string - Search result type (e.g., "default")
  • filter?: 'recent' | 'profiles' - Filter results by type
  • lsd?: string - LSD token (recommended to avoid rate limits)

Returns: Promise<ThreadItem[]> (same structure as fetchThreadsData)

Examples:

// Basic search
const results = await searchPosts('threads');

// Search with serp_type
const results = await searchPosts('threads', { serp_type: 'default' });

// Search with filter
const recentResults = await searchPosts('threads', { filter: 'recent' });
const profileResults = await searchPosts('threads', { filter: 'profiles' });

// Search with both parameters
const results = await searchPosts('threads', { 
  serp_type: 'default', 
  filter: 'recent' 
});

// Search with LSD token (recommended to avoid rate limits)
const { lsd } = await extractTokens('zuck');
const results = await searchPosts('threads', { lsd });

// Search with all parameters including LSD token
const results = await searchPosts('threads', { 
  serp_type: 'default', 
  filter: 'recent',
  lsd 
});

License

MIT