threads-api

name	threads-api
description	Threads API Documentation

Threads API Skill

Comprehensive assistance with Meta's Threads API development for building applications that integrate with the Threads social platform.

When to Use This Skill

This skill should be triggered when you are:

• Building Threads integrations - Creating apps that post to or read from Threads
• Implementing authentication - Setting up OAuth flows for Threads API access
• Working with media uploads - Uploading images, videos, or carousel posts to Threads
• Managing user content - Publishing, retrieving, or managing Threads posts
• Fetching analytics - Retrieving insights and metrics for Threads content
• Handling webhooks - Processing real-time updates from Threads
• Troubleshooting API errors - Debugging authentication, rate limits, or API responses
• Reading Threads profiles - Fetching user profile data and posts

Quick Reference

Authentication - Getting an Access Token

// Step 1: Redirect user to authorization endpoint
const authUrl = `https://threads.net/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=threads_basic,threads_content_publish&response_type=code`;

// Step 2: Exchange authorization code for access token
const response = await fetch('https://graph.threads.net/oauth/access_token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    grant_type: 'authorization_code',
    redirect_uri: REDIRECT_URI,
    code: authorizationCode
  })
});

const { access_token } = await response.json();

Publishing a Text Post

// Create a simple text post
const response = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    media_type: 'TEXT',
    text: 'Hello from Threads API! 🎉'
  })
});

const data = await response.json();
console.log('Post ID:', data.id);

Publishing an Image Post

import requests

# Upload and publish an image
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "IMAGE",
    "image_url": "https://example.com/image.jpg",
    "text": "Check out this image! #API"
}

response = requests.post(url, headers=headers, json=data)
post_id = response.json()["id"]
print(f"Posted image with ID: {post_id}")

Publishing a Video Post

// Step 1: Create a video container
const container = await fetch(`https://graph.threads.net/v1.0/me/threads`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({
    media_type: 'VIDEO',
    video_url: 'https://example.com/video.mp4',
    text: 'Check out this video!'
  })
});

const { id: containerId } = await container.json();

// Step 2: Publish the container
await fetch(`https://graph.threads.net/v1.0/me/threads_publish`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${accessToken}` },
  body: JSON.stringify({ creation_id: containerId })
});

Fetching User Profile

import requests

# Get authenticated user's profile
url = f"https://graph.threads.net/v1.0/me"
headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "fields": "id,username,name,threads_profile_picture_url,threads_biography"
}

response = requests.get(url, headers=headers, params=params)
profile = response.json()

print(f"Username: {profile['username']}")
print(f"Bio: {profile['threads_biography']}")

Fetching User's Threads

// Get user's recent threads with pagination
const response = await fetch(
  `https://graph.threads.net/v1.0/me/threads?fields=id,text,timestamp,media_url&limit=25`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data, paging } = await response.json();
data.forEach(thread => {
  console.log(`${thread.timestamp}: ${thread.text}`);
});

// Use paging.next for next page

Publishing a Carousel Post

import requests

# Create a carousel with multiple images
url = "https://graph.threads.net/v1.0/me/threads"
headers = {"Authorization": f"Bearer {access_token}"}

data = {
    "media_type": "CAROUSEL",
    "children": [
        {"media_type": "IMAGE", "image_url": "https://example.com/img1.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img2.jpg"},
        {"media_type": "IMAGE", "image_url": "https://example.com/img3.jpg"}
    ],
    "text": "Swipe through these images! 📸"
}

response = requests.post(url, headers=headers, json=data)
carousel_id = response.json()["id"]

Retrieving Insights (Analytics)

// Get insights for a specific thread
const threadId = '123456789';
const response = await fetch(
  `https://graph.threads.net/v1.0/${threadId}/insights?metric=views,likes,replies,reposts`,
  {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  }
);

const { data } = await response.json();
data.forEach(metric => {
  console.log(`${metric.name}: ${metric.values[0].value}`);
});

Error Handling Pattern

import requests

def make_threads_request(url, access_token, method='GET', **kwargs):
    """Robust error handling for Threads API requests"""
    headers = kwargs.pop('headers', {})
    headers['Authorization'] = f"Bearer {access_token}"

    try:
        response = requests.request(method, url, headers=headers, **kwargs)
        response.raise_for_status()
        return response.json()

    except requests.exceptions.HTTPError as e:
        error_data = e.response.json()
        error_code = error_data.get('error', {}).get('code')
        error_msg = error_data.get('error', {}).get('message')

        if error_code == 190:
            raise Exception(f"Invalid access token: {error_msg}")
        elif error_code == 32:
            raise Exception(f"Rate limit exceeded: {error_msg}")
        else:
            raise Exception(f"API Error {error_code}: {error_msg}")

    except requests.exceptions.RequestException as e:
        raise Exception(f"Network error: {str(e)}")

Key Concepts

Access Tokens and Permissions

• Access Tokens: OAuth 2.0 tokens required for all API requests
• Scopes: Define what your app can access (e.g., threads_basic, threads_content_publish, threads_manage_insights)
• Token Expiration: Long-lived tokens (60 days) and refresh tokens for extended access

Media Types

• TEXT: Simple text posts
• IMAGE: Single image with optional caption
• VIDEO: Single video with optional caption
• CAROUSEL: Multiple images or videos in a swipeable format

Publishing Flow

1. Container Creation: Create a media container with content
2. Publishing: Publish the container to make it visible
3. Two-stage process: Required for videos and carousels to allow processing time

Rate Limits

Threads API rate limits are calculated based on a rolling 24-hour window and are unique to each app-user pair.

• Publishing Limits (Per Profile):
  • Posts: 250 API-published posts per 24 hours. (A carousel counts as one post).
  • Replies: 1,000 replies per 24 hours.
  • Deletions: 100 deletions per 24 hours.
• General API Call Quota:
  • The quota is calculated using the formula: 4,800 × Number of Impressions.
  • Minimum Floor: If an account has fewer than 10 impressions, the API defaults to 10, providing a minimum of 48,000 calls per 24 hours.

Media Constraints

All media must be hosted on a publicly accessible server so Meta's servers can fetch the content during the container creation process.

Text Posts

• Character Limit: 500 characters maximum.
• Links: Maximum of 5 links (includes both inline links and link attachments).

Image Specifications

• Formats: JPEG, PNG.
• File Size: 8 MB maximum.
• Aspect Ratio: Up to 10:1.
• Dimensions: Width between 320px and 1440px.
• Color Space: sRGB (other spaces will be converted).

Video Specifications

• Formats: MP4, MOV (MPEG-4 Part 14).
• Duration: 300 seconds (5 minutes) maximum.
• File Size: 1 GB maximum.
• Video Codec: H.264 or HEVC, progressive scan, closed GOP, 4:2:0 chroma subsampling.
• Audio Codec: AAC, 48khz max, mono or stereo.
• Frame Rate: 23–60 FPS.
• Resolution: Maximum width of 1920px.

Carousel Posts

• Item Count: Minimum of 2 and maximum of 20 items.
• Content: Can be a mix of images and videos.

Monitoring Usage

You can programmatically check a profile's current rate limit status by querying the GET /{threads-user-id}/threads_publishing_limit endpoint. This returns quota_usage and quota_total for the current 24-hour window.

Webhooks

• Real-time notifications for events like mentions, replies, or new followers
• Requires HTTPS endpoint for receiving notifications
• Must validate webhook signatures for security

Reference Files

This skill includes comprehensive documentation in references/:

• other.md - Complete Threads API documentation including:
  • Authentication and authorization flows
  • API endpoints reference
  • Request/response formats
  • Error codes and troubleshooting
  • Best practices and guidelines

Use the skill's reference files when you need detailed information about specific API endpoints, parameters, or advanced features.

Working with This Skill

For Beginners

Start by understanding the authentication flow - this is the foundation of all Threads API integrations. Focus on:

1. Setting up your Meta developer account and app
2. Implementing OAuth 2.0 authorization
3. Making your first API request to fetch user profile
4. Publishing a simple text post

For Intermediate Users

Build on the basics by exploring:

1. Media uploads (images and videos)
2. Carousel posts for multi-image content
3. Webhook integration for real-time updates
4. Error handling and retry logic
5. Rate limit management

For Advanced Users

Optimize your integration with:

1. Insights and analytics data
2. Batch operations for efficiency
3. Advanced content scheduling
4. Custom webhook event processing
5. Multi-account management

Navigation Tips

• Quick Reference: Use the code examples above for common tasks
• Reference Files: Dive into references/other.md for complete API documentation
• Authentication First: Always start with proper authentication setup
• Test in Sandbox: Use Meta's test users and sandbox environment during development

Common Workflows

Complete Post Publishing Flow

1. Obtain access token via OAuth flow
2. Create media container (if using images/videos)
3. Wait for container processing (for videos)
4. Publish the container
5. Retrieve post ID and insights

User Data Retrieval Flow

1. Authenticate user
2. Fetch user profile with required fields
3. Retrieve user's threads with pagination
4. Process and display content

Webhook Integration Flow

1. Set up HTTPS endpoint
2. Register webhook subscription
3. Validate webhook signatures
4. Process incoming events
5. Respond with 200 OK status

Best Practices

1. Security

   • Never expose access tokens in client-side code
   • Always validate webhook signatures
   • Use environment variables for sensitive data
   • Implement token refresh before expiration

2. Performance

   • Cache API responses when appropriate
   • Use batch requests for multiple operations
   • Implement pagination for large result sets
   • Monitor and respect rate limits

3. User Experience

   • Provide clear error messages to users
   • Show loading states during API calls
   • Handle network failures gracefully
   • Request only necessary permissions

4. Content Publishing

   • Validate media URLs before uploading
   • Check media format requirements
   • Add appropriate error handling for failed uploads
   • Consider using alt text for accessibility

Resources

Official Documentation

• Meta for Developers: https://developers.facebook.com/docs/threads
• API Reference: Available in references/other.md

Developer Tools

• Meta App Dashboard: Configure your app and manage permissions
• Graph API Explorer: Test API calls interactively
• Webhook Testing: Test webhook endpoints before production

Troubleshooting

Common Issues

Authentication Errors (Code 190)

• Check access token validity
• Verify token hasn't expired
• Ensure correct permissions/scopes

Rate Limit Errors (Code 32)

• Implement exponential backoff
• Monitor API usage
• Consider caching responses

Media Upload Failures

• Verify media URL is publicly accessible
• Check file format and size requirements
• Ensure proper media_type parameter

Webhook Not Receiving Events

• Verify endpoint is HTTPS
• Check webhook signature validation
• Ensure endpoint responds with 200 OK quickly

Notes

• This skill was generated from Meta's official Threads API documentation
• The Threads API is part of Meta's Graph API family
• API features and endpoints may be updated by Meta - refer to official docs for latest changes
• Some features may require additional app review or permissions from Meta

Updating

To refresh this skill with updated documentation:

1. Visit https://developers.facebook.com/docs/threads for the latest information
2. Re-run the documentation scraper with updated configuration
3. The skill will be rebuilt with current API information