Threads API

Building with an AI assistant?

This page is the complete Threads API reference for Postproxy — every format, parameter, media limit, and example in one place. Click Copy page at the top to copy it as Markdown, then paste it into ChatGPT, Claude, Cursor, or any LLM and it’ll have everything it needs to write your integration.

Postproxy publishes feed posts and multi-post chains to Threads, and lets you read and reply to comments. Threads has no direct-message API.

Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.

Profiles and profile groups

Every post targets one or more profiles. A profile is one connected account — for Threads, a Threads account. Reference one in a request by its id (the prof_abc123 in the examples below) or by the platform name "threads", which selects the group’s Threads profile (a group holds at most one profile per platform). List what’s connected with GET /api/profiles.

Profiles live in profile groups — containers that organize the accounts for one brand, client, or project. List groups with GET /api/profile_groups, and connect a new Threads profile with the Initialize Connection endpoint.

Example: get profiles and profile groups

List the profiles you can post to — GET /api/profiles:

curl -X GET "https://api.postproxy.dev/api/profiles" \
     -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "prof_abc123",
      "name": "@mycompany",
      "platform": "threads",
      "status": "active",
      "profile_group_id": "grp_xyz789",
      "expires_at": null,
      "post_count": 38,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof_abc123.jpg"
    }
  ]
}

List your profile groups — GET /api/profile_groups:

curl -X GET "https://api.postproxy.dev/api/profile_groups" \
     -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    { "id": "grp_xyz789", "name": "Main Brand", "profiles_count": 5 },
    { "id": "grp_def456", "name": "Client Project", "profiles_count": 3 }
  ]
}

At a glance

Platform ID	threads
Formats	post (default)
Character limit	500
Media	Optional
Comments	List, reply, hide/unhide
Direct messages	No
Post chains	Yes

Publishing

Parameters

Threads has no custom parameters — pass an empty object (or omit it).

Media	Max size	Formats	Count	Duration
Image	8 MB	jpg, png, gif, webp	20	—
Video	1 GB	mp4, mov	1	up to 5 min

• Text-only posts are allowed; media is optional.
• Images and a video can be mixed in a carousel (up to 20 items).
• Minimum image dimensions: 200×200 px.

# Simple post with an image
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Exciting announcement coming soon! Stay tuned." },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/image.jpg"],
       "platforms": { "threads": {} }
     }'

Post chains

Threads supports native thread conversations. Pass a thread array of follow-up posts; each child can carry its own media.

# A 3-post thread
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "1/ Here is a thread about our launch" },
       "profiles": ["prof_abc123"],
       "thread": [
         { "body": "2/ First, we built the foundation...", "media": ["https://example.com/shot.jpg"] },
         { "body": "3/ Check it out at example.com" }
       ]
     }'

Comments

Threads comments are managed through the Comments API. All comment writes are asynchronous and need the profile_id query parameter.

Action	Supported
List / read	Yes
Reply	Yes
Hide / unhide	Yes
Delete	No
Like / unlike	No

• Comment attachments can carry IMAGE, VIDEO, AUDIO, and GIF media on both top-level comments and replies.
• A comment.created webhook fires when a new comment is synced.

# List comments on a post
curl "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Reply to a comment
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "body": "Glad you liked it!", "parent_id": "cmt_abc123" }'

# Hide / unhide a comment
curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/hide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.postproxy.dev/api/posts/post_abc123/comments/cmt_abc123/unhide?profile_id=prof_abc123" \
     -H "Authorization: Bearer YOUR_API_KEY"

Direct messages

Not supported — Threads has no DM API. Calls to the Direct Messages API for a Threads profile return 422.

Stats

Postproxy records periodic stat snapshots you can pull as a timeseries; field names pass through from Threads unchanged.

Profile stats

Account-level metrics, refreshed roughly every 23 hours via the Profile stats endpoint (GET /api/profiles/:id/stats).

Fields: followers_count, views, likes, replies, reposts, quotes

# Fetch the profile stats timeseries
curl "https://api.postproxy.dev/api/profiles/prof_abc123/stats" \
     -H "Authorization: Bearer YOUR_API_KEY"

Post stats

Per-post engagement, captured after publish via the Post stats endpoint (GET /api/posts/stats).

Fields: impressions, likes, replies, reposts, quotes, shares

# Fetch post stats
curl "https://api.postproxy.dev/api/posts/stats?post_ids=post_abc123&profiles=threads" \
     -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Subscribe with the Webhooks API:

curl -X POST "https://api.postproxy.dev/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhooks/postproxy",
       "events": ["platform_post.published", "comment.created"]
     }'

Events relevant to Threads:

Event	When
post.processed	A post is ready to publish
platform_post.published	A post was published to the platform
platform_post.failed	A post failed to publish (retries exhausted)
platform_post.failed_waiting_for_retry	A publish attempt failed; will retry
platform_post.insights	New analytics snapshot
comment.created	A comment was synced on a Threads post
profile.connected / .disconnected	Connection state changed
profile.stats	New profile stats snapshot
media.failed	A media attachment failed to process

Notes

• The 500-character limit is strict — longer copy should be split across a post chain.
• Threads comments cannot be deleted or liked through the API.