Threads Media posts API
API health
- 24h health
- Normal
- Healthy / normal
- Available
- Limited
- Mostly down
Last 24 hours
Last 30 days
List the posts of a Threads account that carry images or video, from username (a handle or profile link). Each row has text, author, like, comment, repost, quote and share counts, post time and media, one entry per file. File links are signed and expire. Each call returns one page of up to 10 posts, and limit has no effect. For the next page, pass the response's next_page_token back as page_token; the last page has none.
Send POST https://api.everyinfra.com/api/v1/social with platform set to threads and action set to user_media. Price $0.56 per 1,000 requests ($0.000556 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.
AI prompt
#Please help me write a data collection script with the EveryInfra Threads Media posts endpoint (threads/user_media).
How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to threads and action to user_media, and put the parameters inside params.
- Required parameters:
- username: Specifies the Threads handle (with or without @) for profile, user_posts, followers, user_replies, user_media, user_reposts, followers_list, following_list and engagement.
- Optional parameters:
- page_token: Page token. Leave it out for the first page, then pass back the previous response's next_page_token exactly as received, with the other parameters unchanged. Each page holds up to 10 posts and is one call.
- Returns a list of records. Main fields of each record: id, code (Post code: the segment of the post link…), url, text, author_username, author_name, author_id, author_avatar_url (Author avatar URL), author_is_verified (Whether the author's account has a veri…), author_is_private (Whether the author's account is private), author_follower_count, like_count; 75 fields in total, full list at https://api.everyinfra.com/api/v1/social/catalog?platform=threads.
- Example request body:
{
"platform": "threads",
"action": "user_media",
"params": {
"username": "zuck"
}
}
- Price: $0.56 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.
Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.Request parameters
#| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
Authorization | header | string | Yes | - | Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository. |
platform | body | string | Yes | threads | Platform identifier, fixed value. |
action | body | string | Yes | user_media | Capability identifier, fixed value. |
username | body.params | string | Yes | - | Specifies the Threads handle (with or without @) for profile, user_posts, followers, user_replies, user_media, user_reposts, followers_list, following_list and engagement. The profile and user_posts actions do not accept full profile URLs; user_replies, user_media, user_reposts, followers_list, following_list and engagement also accept a profile link such as https://www.threads.com/@mosseri. The followers action returns aggregate follower counts; use followers_list and following_list for the accounts themselves. |
page_token | body.params | string | No | - | Page token. Leave it out for the first page, then pass back the previous response's next_page_token exactly as received, with the other parameters unchanged. Each page holds up to 10 posts and is one call; limit has no effect. Tokens last 24 hours; the last page has no next_page_token. |
Code samples
#curl -X POST 'https://api.everyinfra.com/api/v1/social' \
-H "Authorization: Bearer $EVERYINFRA_API_KEY" \
-H 'Content-Type: application/json' \
--data-raw '{
"platform": "threads",
"action": "user_media",
"params": {
"username": "zuck"
}
}'OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.
Response example
#{ "id": "req_…", "platform": "threads", "action": "user_media", "results": [ { "id": …, "code": …, "url": …, "text": …, "author_username": …, "author_name": …, "author_id": …, "author_avatar_url": …, "author_is_verified": …, "author_is_private": …, "author_follower_count": …, "like_count": …, "comment_count": …, "repost_count": …, "quote_count": …, "share_count": …, "posted_at": …, "media_type": …, "image_count": …, "video_count": …, "media_url": …, "video_duration_seconds": …, "topic": …, "topic_id": …, "topic_name": …, "topic_emoji": …, "topic_is_community": …, "language": …, "is_edited": …, "is_reply": …, "reply_to_username": …, "root_post_author_username": …, "reply_level": …, "is_pinned": …, "is_pinned_by_author": …, "is_spoiler": …, "reply_control": …, "counts_hidden": …, "thread_id": …, "thread_length": …, "thread_position": …, "is_federated": …, "is_paid_partnership": …, "ai_label": …, "text_translation": …, "attached_text": …, "fediverse_like_count": …, "fediverse_reply_count": …, "is_liked_by_author": …, "is_collapsed": …, "reply_approval_enabled": …, "is_ghost_post": …, "ghost_expires_at": …, "is_markup": …, "hashtags": …, "mentions": …, "links": …, "image_urls": …, "video_urls": …, "tagged_users": …, "media": …, "link_preview": …, "location": …, "quoted_post": …, "reposted_post": …, "gif": …, "music": …, "podcast": …, "scorecard": …, "trend": …, "author_badge": …, "custom_like": …, "platform": …, "in_reply_to": …, "reposted_by": …, "reposted_at": … } ], "next_page_token": …, "pagination": { … }, "count": …, "billing": { "charged": …, "charged_usd": …, "balance_after_usd": …, … }, "quota": { … }}
Response fields
#Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.
| Field | Meaning |
|---|---|
id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
code | Post code: the segment of the post link that comes after /post/. |
url | Link to the record on the platform. |
text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
author_username | Author's username (@handle), usually usable in URLs. |
author_name | Author's display name. |
author_id | Author's unique ID on the platform. |
author_avatar_url | Author avatar URL; signed link that expires. |
author_is_verified | Whether the author's account has a verified badge. |
author_is_private | Whether the author's account is private. |
author_follower_count | Author's follower count. null means not disclosed. |
like_count | Likes. null means the platform or this capability does not disclose it; it is not 0. |
comment_count | Comments. null means not disclosed, not 0. |
repost_count | Reposts (as distinct from quote posts). null means not disclosed. |
quote_count | Quotes: how many times others have quoted this post in their own posts. null means not disclosed, not 0. |
share_count | Shares. null means not disclosed, not 0. |
posted_at | Publish time in ISO 8601, UTC (for example 2026-08-07T12:34:56+00:00). Non-standard strings from the platform are passed through as is, so parse defensively. null means the platform does not disclose it. |
media_type | Post type: text (text only), image (one image), video (one video) or carousel (several images, or images and videos mixed). |
image_count | Number of images. |
video_count | Number of videos. |
media_url | URL of the first attachment; signed link that expires. |
video_duration_seconds | Duration of the first video, in seconds; per-video durations are in duration_seconds on each media entry. |
topic | Internal name of the topic the post is attached to, e.g. bakingthreads; the display name is in topic_name. |
topic_id | ID of the topic the post is attached to. |
topic_name | Display name of the topic, e.g. Baking Threads. |
topic_emoji | Emoji icon of the topic (community). |
topic_is_community | Whether the topic is a community. |
language | Content language code (for example zh, en) as judged by the platform; it can be wrong. |
is_edited | Whether the post has been edited. |
is_reply | Whether this post is a reply. |
reply_to_username | Username of the person this post replies to; absent when the post is not a reply. |
root_post_author_username | Username of the author of the post at the top of this conversation. |
reply_level | Reply depth: 1 is a direct reply to the main post, 2 is a reply to a reply, and so on. |
is_pinned | Whether the author pinned the post to their profile. |
is_pinned_by_author | Replies only: whether the main post's author pinned it in the replies section. |
is_spoiler | Whether the post is marked with a spoiler overlay. |
reply_control | Who can reply to this post, e.g. everyone. |
counts_hidden | Whether the author hid the like and share counts; like_count is null when hidden. |
thread_id | ID of the author's thread, the run of posts published in a row; posts in the same thread share this value. |
thread_length | Number of posts in the author's thread; 1 when the post is not part of a thread. |
thread_position | Position of this post within the thread. |
is_federated | Whether the post is synced to the fediverse. |
is_paid_partnership | Whether the post is labeled as a paid partnership. Use it to identify ads. |
ai_label | How the post is labeled as AI-generated, e.g. SELF_DISCLOSURE_FLOW (labeled by the author); absent when there is none. |
text_translation | Threads' English translation of the text; present only when the text is not in English and Threads provides a translation. |
attached_text | Full text of the long-form text attachment on the post (the Threads text attachment). |
fediverse_like_count | Like count on the fediverse side (Mastodon and others). |
fediverse_reply_count | Reply count on the fediverse side. |
is_liked_by_author | Replies only: whether the main post's author liked this reply. |
is_collapsed | Replies only: the platform collapsed this reply. Present only when true. |
reply_approval_enabled | The author turned on reply approval, so replies need approval first. Present only when true. |
is_ghost_post | The post is a ghost post, a time-limited post that disappears automatically after a while. Present only when true. |
ghost_expires_at | Time when the ghost post disappears. |
is_markup | The post is a Markup post, drawn or annotated on top of someone else's post. Present only when true. |
hashtags | Hashtags in the text, in order of appearance; absent when there are none. |
mentions | Usernames @-mentioned in the text. |
links | Links in the text and links attached to the post. |
image_urls | Array of image links in the platform's display order; absent when there are no images. |
video_urls | URLs of all videos; signed links that expire. |
tagged_users | Usernames of the people tagged in the images and videos. |
media | List of attachments, one entry each; absent when there are none. Each entry: type (image or video), url (file URL, signed link that expires), width and height (pixels), alt_text (alternative text, generated by Threads or written by the author); videos also carry thumbnail_url (cover image), has_audio (whether it has sound) and duration_seconds (length in seconds). |
link_preview | Link card: url, title (card title), description (card description), display_url (displayed domain), image_url (card image) and favicon_url (site favicon). |
location | Location attached to the post: id (location ID), name (location name) and url (this location's page on Threads). |
quoted_post | The original post this post quotes: id, code, url, text, author_username and posted_at. |
reposted_post | The original post this post reposts, with the same structure as quoted_post. |
gif | GIF in the post: url, webp_url (WebP-format URL), width and height (both in pixels). |
music | Music attached to the post: song_id, title (song title), artist, cover_url (cover image) and start_ms (millisecond of the song where playback starts); lyrics are not included. |
podcast | On posts, the podcast episode card attached to the post: episode_name, episode_url, podcast_name, platform (podcast platform, e.g. SPOTIFY, APPLE) and image_url. In profile (account data), the podcast attached to the profile page: name, url, platform and image_url, and for some also links (listening links per platform, each with platform and url). |
scorecard | Sports scorecard attached to the post: status (upcoming: not started, live: in progress, past: finished), starts_at (start time), clock (game clock), period (which period, e.g. Q4), home_team and away_team (each with name, short_name, score and logo_url) and url (link at the bottom of the card). |
trend | The trend this post appears under: keyword (the trend's search term), id and summary (summary written by the platform; only some have it). |
author_badge | The author's badge in this community: type (badge type, e.g. MEMBER) and label (identity label the author chose in the community, e.g. a team name). |
custom_like | Custom like style that replaces the default heart on this post: type (EMOJI or STICKER), emoji and sticker_url (sticker GIF URL). |
platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |
in_reply_to | The post this reply answers: id, code, url, text, author_username, author_name, like_count, comment_count and posted_at. |
reposted_by | The account (username) that reposted this post; the row itself is the original post that was reposted. |
reposted_at | When the post was reposted. |
Errors and billing
#- 401
- Missing or invalid key.
- 402
- Insufficient balance. Top up first.
- 422
- Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
- 429
- Per-minute request limit reached. Wait for Retry-After, then try again.
- 503
- Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
- 200 empty
- No data. No charge.