Meta Threads API Developer Guide
A practical developer guide to building on the Threads API — connection, publishing, and limits.
By André LugThe Threads API authenticates through Meta OAuth (shared with Instagram and Facebook), publishes through a create-container-then-publish flow that PostGate wraps in one POST /api/posts call, caps text at 500 UTF-8 bytes, and allows 250 published posts per profile per rolling 24 hours. Scheduling isn't native — PostGate's queue holds and fires the post.
This is the reference page for building on Threads through PostGate: how the connection works, what a publish request looks like, what carousels and scheduling actually do underneath, and where the real limits are. Each section links to a focused page if you need the full detail.
How does the Meta OAuth connection work?
pro_threads_... profile ID that every future request reuses. Tokens are refreshed proactively in the background, roughly a week before expiry, so a healthy connection doesn't need manual reconnection. When it does need re-consent, GET /api/profiles/{id}/health reports reconnect_required before a publish attempt wastes a request.How does publishing work under the hood?
POST /api/posts takes a post body, the target Threads profile ID, and an optional media array. Under the hood, Meta's Graph API requires creating a media container, waiting for it to finish processing, then calling a separate publish step with the container ID — PostGate runs that whole sequence per request and checkpoints the container ID, so a retried request never creates a duplicate container. See Threads API: post to a profile for the exact request, or the full walkthrough for every step from connection onward.curl -X POST "https://postgate.studio/api/posts" \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: threads-guide-001" \
-d '{
"post": { "body": "Announcing something new." },
"profiles": ["pro_threads_8f21"],
"media": ["https://cdn.example.com/announcement.jpg"]
}'What are the content limits?
Is scheduling native to Threads?
scheduled_publish_time field to set. PostGate's own scheduler holds a post with a future scheduled_at and fires the identical publish flow when the time comes, or materializes posts from a recurring cron/slot template via POST /api/schedules. Full detail in Threads scheduling.How do the rate limits work?
Why does this work without your own app review?
How do you confirm delivery?
GET /api/posts/{id} for its status and permalink, or subscribe to a terminal webhook instead of polling. A failed target carries a structured error; awaiting_reconnect means the customer needs to re-approve the Meta connection before the retry can succeed.Frequently asked questions
Does Threads have its own login for API access?
No — Threads has no separate login of its own. It authenticates through the same Meta OAuth consent screen as Instagram and Facebook Pages. PostGate stores the result as a durable pro_threads_ profile ID and refreshes tokens proactively in the background, roughly a week before expiry, so a healthy connection does not need manual reconnection.
What are the Threads API content limits?
Text posts are capped at 500 UTF-8 bytes. A single post takes one image (JPEG, up to 8 MB, 320–1440px wide) or one video (up to 1 GB, 5 minutes). PNG is documented by Meta as accepted but rejected by the live API — PostGate converts images to JPEG automatically. Carousels take 2 to 20 mixed image/video items and count as a single post.
Can I schedule posts natively through the Threads API?
No. Meta's Threads API only ever publishes immediately — there is no scheduled_publish_time field to set. PostGate's own scheduler holds a post with a future scheduled_at and fires the identical publish flow when the time comes, or materializes posts from a recurring cron/slot template via POST /api/schedules.
What is the Threads API rate limit?
Meta caps each Threads profile at 250 published posts per rolling 24 hours, tracked independently from a 1,000-reply daily quota. It is a quota, not a requests-per-second throttle, and PostGate tracks it per profile so activity on one connected account does not affect another.
Do I need Meta app review to publish to Threads?
Publishing to a real customer's Threads profile — not just your own developer account — requires Meta's content-publishing permission to clear app review, a process that runs independently for Threads even if your app is already approved for Instagram or Facebook. PostGate already holds that reviewed permission, so connecting through PostGate's OAuth flow skips that wait entirely.
