threads-graph-api

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

⚠️ Warning!

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.

Overview

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.

Installation

Install the package with your favorite package manager:

$ yarn add threads-graph-api

or

$ npm install threads-graph-api

Usage

threads-graph-api follows the official Threads API documentation for endpoints and parameters. See types.ts for all request and response schemas.

Initializing the Client

There are two types of clients provided by the library:

• ThreadsPublicApiClient
• ThreadsAuthenticatedApiClient

Public API Client

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
);

Authenticated API Client

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
);

Authentication

Creating Authorization URL

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
);

Exchanging an Authorization Code

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);

Using the API

Creating a media container

To create a media container:

const params = {
  mediaType: 'TEXT',
  text: 'Hello, World!',
};

const response = await authenticatedClient.createMediaContainer(params);

Publishing media

To publish a media container:

const params = {
  creationId: 'media-creation-id',
};

const response = await authenticatedClient.publish(params);

Getting a user's threads

To get user threads:

const params = {
  id: 'user-id',
  fields: ['id', 'media_type', 'media_url'],
};

const response = await authenticatedClient.getUserThreads(params);

Getting a media object

To get a media object:

const params = {
  id: 'media-id',
  fields: ['id', 'media_type', 'media_url'],
};

const response = await authenticatedClient.getMediaObject(params);

Getting a user's profile

To get a user's profile:

const params = {
  id: 'user-id',
  fields: ['id', 'username', 'threads_profile_picture_url'],
};

const response = await authenticatedClient.getUserProfile(params);

Getting a user's threads publishing limit

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);

Getting thread replies

To get a thread's replies:

const params = {
  id: 'media-id',
  fields: ['id', 'text', 'username'],
  reverse: true,
};

const response = await authenticatedClient.getReplies(params);

Getting a thread conversation

To get a thread's conversation:

const params = {
  id: 'conversation-id',
  fields: ['id', 'text', 'username'],
  reverse: true,
};

const response = await authenticatedClient.getConversation(params);

Managing a reply

To manage a reply:

const params = {
  id: 'reply-id',
  hide: true,
};

const response = await authenticatedClient.manageReply(params);

Getting media metrics

To get media metrics:

const params = {
  id: 'media-id',
  metrics: ['views', 'likes'],
};

const response = await authenticatedClient.getMediaMetrics(params);

Getting account metrics

To get account metrics:

const params = {
  id: 'user-id',
  metrics: ['followers_count'],
};

const response = await authenticatedClient.getAccountMetrics(params);

Handling errors

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);
  }
}

Contributing

Contributions are welcome (and encouraged)! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.