threads-api-client

Official TypeScript/JavaScript SDK for thredly — Threads & Instagram data API

---

Installation

npm install threads-api-client
# or
pnpm add threads-api-client
# or
yarn add threads-api-client

Requirements: Node.js 18+ (uses native fetch). Zero runtime dependencies.

---

Quick Start

import { ThredlyClient } from 'threads-api-client';

const client = new ThredlyClient({ apiKey: 'your-api-key' });

// 1. Look up a user
const userInfo = await client.getUserInfo('zuck');
console.log(userInfo.userId); // "314216"

// 2. Get their posts
const posts = await client.getUserPosts(userInfo.userId);
console.log(posts.data);

// 3. Search for content
const results = await client.searchTop('artificial intelligence');
console.log(results.data);

Get your API key at thredly.dev.

---

Configuration

const client = new ThredlyClient({
  apiKey: 'your-api-key',   // required
  baseUrl: 'https://thredly.dev/api', // optional, this is the default
});

---

API Reference

All methods return Promise<ApiResponse<T>> where ApiResponse is:

interface ApiResponse<T = unknown> {
  ok: boolean;
  data?: T;
  error?: string;
}

User Methods

Method	Signature	Endpoint
getUserInfo	(username: string)	GET /user/info?username=
getUser	(userId: string)	GET /user/:userId
getUserPosts	(userId, opts?)	GET /user/:userId/posts
getUserReposts	(userId, opts?)	GET /user/:userId/reposts
getUserReplies	(userId, opts?)	GET /user/:userId/replies
getUserFollowers	(userId, opts?)	GET /user/:userId/followers
getUserFollowing	(userId, opts?)	GET /user/:userId/following
getUserMedia	(userId, opts?)	GET /user/:userId/media

Post Methods

Method	Signature	Endpoint
getPostIdByUrl	(url: string)	GET /post/id-by-url?url=
getPost	(postId: string)	GET /post/:postId
getRelatedPosts	(postId: string)	GET /post/:postId/related
getPostComments	(postId, opts?)	GET /post/:postId/comments
getPostActivity	(postId, opts?)	GET /post/:postId/activity
getPostImpressions	(postId, opts?)	GET /post/:postId/impressions

Search Methods

Method	Signature	Endpoint
searchTop	(query: string, opts?)	GET /search/top?q=
searchRecent	(query: string, opts?)	GET /search/recent?q=
searchProfiles	(query: string, opts?)	GET /search/profiles?q=

Pagination

Paginated endpoints accept { cursor?: string } and return a cursor for the next page:

// First page
const page1 = await client.getUserPosts('314216');

// Next page (if cursor available in response)
const page2 = await client.getUserPosts('314216', { cursor: 'next-cursor-value' });

Comment Sorting

// Sort comments by top engagement (default)
const top = await client.getPostComments('post-id', { sortOrder: 'TOP' });

// Sort by most recent
const recent = await client.getPostComments('post-id', { sortOrder: 'RECENT' });

Impression Options

const impressions = await client.getPostImpressions('post-id', {
  timeWindow: '7d',   // default: 'all'
  bucket: 'hour',     // default: 'day'
});

---

Error Handling

import { ThredlyClient, ThredlyError } from 'threads-api-client';

const client = new ThredlyClient({ apiKey: 'your-api-key' });

try {
  const user = await client.getUserInfo('someuser');
} catch (err) {
  if (err instanceof ThredlyError) {
    console.error(`API error ${err.status}: ${err.message}`);
    // err.status  — HTTP status code (0 for network errors)
    // err.code    — optional error code string
    // err.response — raw response body
  }
}

---

Namespaced Access

Methods are also available via namespaced groups:

// Flat (recommended)
await client.getUserPosts('314216');

// Namespaced
await client.users.getUserPosts('314216');
await client.posts.getPost('post-id');
await client.search.searchTop('threads api');

---

Links

• thredly.dev — API dashboard & docs
• threads-connect — low-level GraphQL client
• thredly-examples — example projects

---

License

MIT © 2026 cipherc09-blip

Not affiliated with Meta or Threads. Use responsibly per platform Terms of Service.