Threads API Integration: Authorization, Posting, & Analytics with Ayrshare
Threads has rapidly emerged as a powerful social platform, leveraging Meta’s infrastructure to provide a text-focused alternative to X (formerly Twitter). With its seamless Instagram integration and growing user base, Threads offers unique opportunities for businesses and developers to reach engaged audiences. Over the past several months we have seen Threads usage expand rapidly amongst our users – while it doesn’t equal Facebook, Instagram, or YouTube, it is getting close to X usage.
Ayrshare has integrated with the Threads API from Meta to provide seamless posting and analytics capabilities through our Social Media API, making it simple to manage your Threads presence programmatically alongside other social platforms.
This blog article covers two approaches: direct integration with the Threads API, and a simplified and more powerful integration using Ayrshare’s Social API.
Let’s explore how you can leverage Threads for your social media strategy, from account linking to content publishing and performance tracking.
Getting Started with the Threads API
The Threads API provides robust capabilities for businesses to programmatically manage their Threads profiles, publish content, and track performance metrics. Built on Meta’s Graph API infrastructure, it offers familiar patterns for developers already working with Facebook or Instagram APIs.
Note: To integrate directly with the Threads API, you must first be approved by Meta.
Authentication Setup
The Threads API uses OAuth 2.0 authentication through Instagram’s authorization flow. This is the same authentication system used for Instagram’s APIs.
First, generate an Instagram authorization URL with the appropriate Threads permissions:
https://api.instagram.com/oauth/authorize
?client_id={app-id}
&redirect_uri={redirect-uri}
&scope=threads_basic,threads_content_publish
&response_type=codeAfter user authorization, exchange the code for access tokens:
const exchangeCodeForToken = async (code, clientId, clientSecret, redirectUri) => {
const url = 'https://api.instagram.com/oauth/access_token';
const formData = new URLSearchParams();
formData.append('client_id', clientId);
formData.append('client_secret', clientSecret);
formData.append('grant_type', 'authorization_code');
formData.append('redirect_uri', redirectUri);
formData.append('code', code);
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded'
},
body: formData
});
const data = await response.json();
// Exchange short-lived token for long-lived token
const longLivedToken = await getLongLivedToken(data.access_token);
return longLivedToken;
};
const getLongLivedToken = async (shortLivedToken) => {
const url = `https://graph.instagram.com/access_token`;
const params = new URLSearchParams({
grant_type: 'ig_exchange_token',
client_secret: CLIENT_SECRET,
access_token: shortLivedToken
});
const response = await fetch(`${url}?${params}`);
return await response.json();
};Publishing a Single Post
Publishing to Threads is a two-step process: create a media container, then publish it. Here’s how to publish different types of content:
Text-Only Post
const publishThreadsTextPost = async (userId, text, accessToken) => {
// Step 1: Create media container
const createUrl = `https://graph.threads.net/${userId}/threads`;
const createResponse = await fetch(createUrl, {
method: 'POST',
body: JSON.stringify({
media_type: 'TEXT',
text: text,
access_token: accessToken
})
});
const container = await createResponse.json();
// Step 2: Publish the container
const publishUrl = `https://graph.threads.net/${userId}/threads_publish`;
const publishResponse = await fetch(publishUrl, {
method: 'POST',
body: JSON.stringify({
creation_id: container.id,
access_token: accessToken
})
});
const result = await publishResponse.json();
return {
status: 'success',
threadId: result.id,
postUrl: `https://www.threads.net/@${username}/post/${result.id}`
};
};Image Post with Text
Threads accepts a media URL of your image. Simply added it to the body to post.
const publishThreadsImagePost = async (userId, imageUrl, text, accessToken) => {
// Step 1: Create media container
const createUrl = `https://graph.threads.net/${userId}/threads`;
const createResponse = await fetch(createUrl, {
method: 'POST',
body: JSON.stringify({
media_type: 'IMAGE',
image_url: imageUrl,
text: text,
access_token: accessToken
})
});
const container = await createResponse.json();
// Wait for processing (recommended 30 seconds)
await new Promise(resolve => setTimeout(resolve, 30000));
// Step 2: Publish the container
const publishUrl = `https://graph.threads.net/${userId}/threads_publish`;
const publishResponse = await fetch(publishUrl, {
method: 'POST',
body: JSON.stringify({
creation_id: container.id,
access_token: accessToken
})
});
return await publishResponse.json();
};Creating Carousel Posts
Threads supports carousel posts with up to 20 images, videos, or a mix of both. This is a three-step process:
const publishThreadsCarousel = async (userId, mediaItems, text, accessToken) => {
// Step 1: Create individual media containers
const itemContainers = [];
for (const item of mediaItems) {
const createUrl = `https://graph.threads.net/${userId}/threads`;
const payload = {
is_carousel_item: true,
media_type: item.type, // 'IMAGE' or 'VIDEO'
access_token: accessToken
};
if (item.type === 'IMAGE') {
payload.image_url = item.url;
} else {
payload.video_url = item.url;
}
const response = await fetch(createUrl, {
method: 'POST',
body: JSON.stringify(payload)
});
const container = await response.json();
itemContainers.push(container.id);
}
// Step 2: Create carousel container
const carouselUrl = `https://graph.threads.net/${userId}/threads`;
const carouselResponse = await fetch(carouselUrl, {
method: 'POST',
body: JSON.stringify({
media_type: 'CAROUSEL',
children: itemContainers.join(','),
text: text,
access_token: accessToken
})
});
const carouselContainer = await carouselResponse.json();
// Step 3: Publish carousel
const publishUrl = `https://graph.threads.net/${userId}/threads_publish`;
const publishResponse = await fetch(publishUrl, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${accessToken}`
},
body: JSON.stringify({
creation_id: carouselContainer.id
})
});
return await publishResponse.json();
};Retrieving Post Insights
While the Threads API is still evolving, you can retrieve basic metrics for your posts:
const getThreadsInsights = async (mediaId, accessToken) => {
const fields = 'id,media_type,media_url,permalink,owner,username,text,timestamp,shortcode,thumbnail_url,children,is_quote_post';
const url = `https://graph.threads.net/${mediaId}?fields=${fields}&access_token=${accessToken}`;
const response = await fetch(url, {
method: 'GET'
});
const data = await response.json();
// Get insights metrics
const insightsUrl = `https://graph.threads.net/${mediaId}/insights`;
const metricsParams = new URLSearchParams({
metric: 'views,likes,replies,reposts,quotes',
access_token: accessToken
});
const insightsResponse = await fetch(`${insightsUrl}?${metricsParams}`);
const insights = await insightsResponse.json();
return {
post: data,
insights: insights.data
};
};
Key Considerations
- Rate Limiting: Threads profiles are limited to 250 API-published posts within a 24-hour moving period.
- Media Processing: Wait approximately 30 seconds after creating media containers before publishing.
- Public Server Requirement: All media URLs must be publicly accessible for Threads to process.
What is Ayrshare’s Threads Integration?
Ayrshare’s Threads API integration simplifies the complexities of working with the Threads API while providing additional features and unified management across multiple social platforms.
With Ayrshare, you can:
- Link Threads accounts without managing OAuth flows
- Publish text, image, video, and carousel posts
- Handle media uploads and processing automatically
- Retrieve comprehensive analytics for your content
- Manage multiple Threads accounts through profile keys
- Schedule posts for optimal timing
How to Link Threads with Ayrshare
Before posting to Threads through Ayrshare, you need to link your Threads account with Ayrshare. The process is streamlined and requires minimal setup.
Prerequisites: Threads Profile Setup
Ensure you have a Threads profile ready:
- Download the Threads app
- Log in with your Instagram account
- Complete your profile setup
- Note: Your Threads handle will match your Instagram handle
Linking Your Account
You can link Threads through Ayrshare’s dashboard or enable your users to link their accounts via the Business Plan social linking page.
Via Dashboard:
- Navigate to the Social Accounts page in your Ayrshare dashboard
- Click the Threads icon
- Log in to Instagram when prompted
- Review and approve the requested permissions
- Your Threads account is now linked!
How to Post to Threads with Ayrshare
Now let’s explore how to publish different types of content to Threads using Ayrshare’s API.
Publishing a Basic Threads Post
Here’s how to publish a simple text post with an optional image:
Example in cURL:
curl \
-H "Authorization: Bearer YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"post": "Just launched our new product! Check it out 🚀 #ProductLaunch",
"platforms": ["threads"],
"mediaUrls": ["https://example.com/product-image.jpg"]
}' \
-X POST https://api.ayrshare.com/api/postExample in JavaScript:
const postToThreads = async () => {
try {
const response = await fetch("https://api.ayrshare.com/api/post", {
method: "POST",
body: JSON.stringify({
post: "Exciting news! Our team just hit a major milestone 🎉",
platforms: ["threads"],
mediaUrls: ["https://example.com/celebration.jpg"],
access_token: accessToken
})
});
const data = await response.json();
console.log("Threads post created:", data);
return data;
} catch (error) {
console.error("Failed to post to Threads:", error);
}
};The response includes:
{
"status": "success",
"id": "625e1e5c8b5d4a001e3b3c5f",
"postIds": {
"threads": {
"id": "17890643139123701",
"status": "success"
}
},
"post": "Exciting news! Our team just hit a major milestone 🎉",
"platforms": ["threads"]
}Publishing Video Content
Threads supports video posts with specific requirements:
Example in Python:
import requests
API_KEY = "YOUR_API_KEY"
url = "https://api.ayrshare.com/api/post"
payload = {
"post": "Behind the scenes of our latest project 🎬",
"platforms": ["threads"],
"mediaUrls": ["https://example.com/behind-scenes.mp4"]
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())Creating Carousel Posts
Publish multiple images or videos as a carousel (up to 20 items):
Example in Node.js:
const axios = require('axios');
const postCarouselToThreads = async () => {
const API_KEY = "YOUR_API_KEY";
try {
const response = await axios.post('https://api.ayrshare.com/api/post', {
post: 'Check out our product lineup! Swipe to see all variants →',
platforms: ['threads'],
mediaUrls: [
'https://example.com/product1.jpg',
'https://example.com/product2.jpg',
'https://example.com/product3.jpg',
'https://example.com/demo-video.mp4'
]
}, {
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json'
}
});
console.log('Carousel posted:', response.data);
return response.data;
} catch (error) {
console.error('Carousel post failed:', error);
}
};Working with Mentions and Hashtags
Threads has specific rules for mentions and hashtags:
{
post: "Great collaboration with @partner on this project! #Innovation",
platforms: ["threads"],
mediaUrls: ["https://example.com/collaboration.jpg"]
}Important Notes:
- Only one hashtag per post is supported
- @mentions will notify the mentioned user
- Maximum 500 characters for post text
- The first URL in text-only posts becomes a link preview (unless media is included)
Media Requirements and Best Practices
When uploading content to Threads, follow these specifications:
Image Guidelines
- Formats: JPEG, PNG, GIF, WEBP
- Maximum file size: 8MB
- Recommended dimensions: 1080 x 1080 px (1:1) or 1080 x 1350 px (4:5)
- Aspect ratios: Between 4:5 and 1.91:1
Video Guidelines
- Format: MP4
- Maximum file size: 500MB
- Duration: 3 seconds to 5 minutes
- Recommended dimensions: 1080 x 1920 px (9:16) for best mobile viewing
- Frame rate: 30 fps recommended
Carousel Guidelines
- Total items: 2-20 images/videos
- Mix allowed: Yes, combine images and videos
- Individual item limits: Same as single image/video posts
How to Get Threads Analytics
Understanding your content performance is crucial for optimizing your Threads strategy. Ayrshare provides analytics data for your Threads posts.
Retrieving Post Analytics
To get analytics for a specific Threads post:
const API_KEY = "YOUR_API_KEY";
const getThreadsAnalytics = async (postId) => {
try {
const response = await fetch("https://api.ayrshare.com/api/analytics/post", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
id: postId,
platforms: ["threads"]
})
});
const analytics = await response.json();
console.log("Threads analytics:", analytics);
return analytics;
} catch (error) {
console.error("Failed to get analytics:", error);
}
};
// Usage
getThreadsAnalytics("625e1e5c8b5d4a001e3b3c5f");The analytics response provides key metrics:
{
"threads": {
"id": "17890643139123701",
"postUrl": "https://www.threads.com/@ayrshare/post/DI4nmXrNQA1",
"analytics": {
"views": 2341,
"likes": 128,
"replies": 23,
"reposts": 15,
"shares": 8,
"quotes": 5
},
"lastUpdated": "2025-01-15T22:41:05.752Z",
"nextUpdate": "2025-01-15T22:52:05.752Z"
}
}These metrics help you understand:
- Views: Total number of times your post was viewed
- Likes: Engagement through likes
- Replies: Conversation generated by your post
- Reposts: How often users shared your content to their followers
- Shares: Direct shares of your post
- Quotes: Times users quoted your post with their own commentary
Managing Multiple Threads Accounts
For agencies or businesses managing multiple Threads accounts, Ayrshare’s Business plan provides Profile Keys for each user:
const postToClientThreads = async (profileKey, content) => {
const response = await fetch("https://api.ayrshare.com/api/post", {
method: "POST",
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Profile-Key": profileKey,
"Content-Type": "application/json"
},
body: JSON.stringify({
post: content.text,
platforms: ["threads"],
mediaUrls: content.mediaUrls
})
});
return await response.json();
};
// Post to different client accounts
await postToClientThreads("client1_profile_key", {
text: "Client 1's product announcement! 📢",
mediaUrls: ["https://example.com/client1-product.jpg"]
});
await postToClientThreads("client2_profile_key", {
text: "Client 2's weekly update thread đź§µ",
mediaUrls: ["https://example.com/client2-update.mp4"]
});Best Practices for Threads Success
Content Optimization
- Keep it conversational: Threads favors authentic, discussion-oriented content
- Use visuals: Posts with images or videos typically see higher engagement
- One hashtag rule: Make your single hashtag count by choosing the most relevant one
- Optimal length: While you have 500 characters, posts between 100-200 characters often perform best
Posting Strategy
- Timing matters: Post when your audience is most active (typically evenings and weekends)
- Consistency: Regular posting helps maintain visibility in followers’ feeds
- Engage quickly: Respond to replies within the first hour for maximum reach
- Cross-promote: Share your Threads handle on other platforms
Technical Best Practices
- Media preparation: Ensure all media is optimized before uploading
- Error handling: Implement retry logic for failed posts
- Rate limit awareness: Track your 24-hour post count to avoid hitting limits
- Webhook integration: Use Ayrshare webhooks to track post status
Analytics-Driven Optimization
- Monitor view-to-engagement ratio: Identify what content resonates
- Track reply sentiment: Understand audience reaction
- Analyze repost patterns: See what content gets shared most
- Compare media types: Test text vs. image vs. video performance
Ayrshare Offers Even More
The Threads API opens up powerful opportunities for programmatic social media management, whether you’re building custom integrations or leveraging Ayrshare’s simplified approach. With its growing user base and unique positioning in the social media landscape, Threads represents an important channel for reaching engaged audiences.
Ayrshare’s integration makes it easy to include Threads in your social media workflow, providing unified management alongside 12+ other platforms including Instagram, Facebook, TikTok, and LinkedIn.
Additional Resources
- Threads API Official Documentation
- Ayrshare Threads API Documentation
- Threads Media Guidelines
- Ayrshare Analytics API
- Meta Graph API Reference
Ready to integrate Threads into your social media strategy? Get started with Ayrshare today and streamline your social media management across all major platforms.