A Javascript library to interface with the official Instagram Threads API. Built by Spool, a Threads creator toolkit with AI-assisted content generation, seamless cross-platform posting, advanced post composing, and more!
Maintainers: @tonypeng, @ishaanbuildsthings
This is an unstable early preview release. Some endpoints may not work and the API is subject to change. Please submit an issue or a pull request if you encounter any issues.
The threads-graph-api repository provides a TypeScript client for interacting with the Instagram Threads API. This library simplifies the process of accessing Instagram's public and authenticated endpoints for managing media, retrieving user profiles, metrics, and more.
Install the package with your favorite package manager:
$ yarn add threads-graph-apior
$ npm install threads-graph-apithreads-graph-api follows the official Threads API documentation for endpoints and parameters. See types.ts for all request and response schemas.
There are two types of clients provided by the library:
ThreadsPublicApiClientThreadsAuthenticatedApiClient
The ThreadsPublicApiClient allows access to endpoints that do not require authentication.
import {ThreadsPublicApiClient} from 'threads-graph-api';
const baseUrl = 'https://graph.threads.net';
const publicClient = new ThreadsPublicApiClient(
baseUrl, // optional
);The ThreadsAuthenticatedApiClient allows access to endpoints that require authentication.
import {ThreadsAuthenticatedApiClient} from 'threads-graph-api';
const accessToken = 'your-access-token';
const userId = 'your-user-id';
const baseUrl = 'https://graph.threads.net'; // you can set this to your own server for testing
const authenticatedClient = new ThreadsAuthenticatedApiClient(
accessToken,
userId,
baseUrl, // optional
);To create an authorization URL:
const clientId = 'your-client-id';
const redirectUri = 'your-redirect-uri';
const scope = ['threads_basic', ...];
const baseUrl = 'https://www.threads.net'; // you can set this to your own server for testing
const authUrl = publicClient.createAuthorizationUrl(
clientId,
redirectUri,
scope,
baseUrl, // optional
);To exchange an authorization code for an access token:
const clientSecret = 'your-client-secret';
const code = 'auth-code';
const response = await publicClient.exchangeAuthorizationCode(clientId, clientSecret, redirectUri, code);To create a media container:
const params = {
mediaType: 'TEXT',
text: 'Hello, World!',
};
const response = await authenticatedClient.createMediaContainer(params);To publish a media container:
const params = {
creationId: 'media-creation-id',
};
const response = await authenticatedClient.publish(params);To get user threads:
const params = {
id: 'user-id',
fields: ['id', 'media_type', 'media_url'],
};
const response = await authenticatedClient.getUserThreads(params);To get a media object:
const params = {
id: 'media-id',
fields: ['id', 'media_type', 'media_url'],
};
const response = await authenticatedClient.getMediaObject(params);To get a user's profile:
const params = {
id: 'user-id',
fields: ['id', 'username', 'threads_profile_picture_url'],
};
const response = await authenticatedClient.getUserProfile(params);To get a user's threads publishing limit:
const params = {
id: 'user-id',
fields: ['reply_quota_usage', 'reply_config'],
};
const response = await authenticatedClient.getUserThreadsPublishingLimit(params);To get a thread's replies:
const params = {
id: 'media-id',
fields: ['id', 'text', 'username'],
reverse: true,
};
const response = await authenticatedClient.getReplies(params);To get a thread's conversation:
const params = {
id: 'conversation-id',
fields: ['id', 'text', 'username'],
reverse: true,
};
const response = await authenticatedClient.getConversation(params);To manage a reply:
const params = {
id: 'reply-id',
hide: true,
};
const response = await authenticatedClient.manageReply(params);To get media metrics:
const params = {
id: 'media-id',
metrics: ['views', 'likes'],
};
const response = await authenticatedClient.getMediaMetrics(params);To get account metrics:
const params = {
id: 'user-id',
metrics: ['followers_count'],
};
const response = await authenticatedClient.getAccountMetrics(params);The ThreadsApiError class is thrown when the Threads API returns an error. The message field of the returned error is accessible from the error field on the ThreadsApiError object. To access other fields, use getThreadsError() to retrieve the full error object returned by the Threads API:
try {
const response = await authenticatedClient.getUserProfile(params);
} catch (error) {
if (error instanceof ThreadsApiError) {
console.error('Threads API Error:', error.message, error.getThreadsError());
} else {
console.error('Unexpected Error:', error);
}
}Contributions are welcome (and encouraged)! Please open an issue or submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.