Skip to content

Threads Profile

POST /api/v1/threads/profile — 1 credit per request

Look up a public Threads profile by handle. Returns the username, display name, bio (as plain text and split into text, links and mentions), bio links, follower count, verified and private flags, and the profile picture at each size. The profile comes in Threads’ own shape, with Threads’ key names. Send the handle as a query parameter.

Method Path Returns
POST /api/v1/threads/profile A public Threads profile
Name Where Type Required Description
handle query string (1 to 30) Yes A Threads username: letters, digits, . and _. One leading @ and surrounding spaces are removed, and case is ignored, so sportsillustrated and @SportsIllustrated are the same lookup
  • handle is the only accepted identifier. A profile URL or a numeric user id is a 400.
  • A handle with a space or -, one made only of dots, or one longer than 30 characters is a 400.
Field Type Description
requestId string Opaque ID for this request (req_…). Quote it when reporting a problem
handle string The handle looked up, lowercase, without @
status string "success" on every 200
coalesced boolean true if this request joined a fetch for the same handle that was already under way
cached boolean true if answered from a fetch of the last 10 minutes. Free if your key already paid for this profile
result object The profile, see below
finishReason string Empty on a freshly fetched answer, absent on a cached one. Ignore it on a 200
success boolean true on every 200
credits_charged integer What this request cost. 0 for a profile your key already paid for
credits_remaining integer Your balance after this request
cached_at string UTC time of the cached answer. Present only on a cached answer

Every key is always present. Where Threads sends nothing, the value is null or an empty list, never a made-up number.

Field Type Description
pk, id string The account’s numeric id. Both carry the same value
username string The account’s handle
full_name string The display name. Empty when the account has none
biography string The bio as plain text. Empty when there is none
text_app_biography object or null The bio split into text_fragments.fragments: plain text, links and mentions
bio_links array Up to 10 links, each { url, is_verified, link_id }. Empty when there are none
follower_count integer or null null is not zero: Threads sent the key empty
is_verified boolean Whether the account is verified
text_post_app_is_private boolean Whether the account is private
has_onboarded_to_text_post_app, show_text_post_app_badge boolean or null null when Threads did not say
profile_pic_url string The profile picture. Expires: download the image, do not store the link
hd_profile_pic_versions array The larger sizes, each { height, width, url }. Empty when there are none
friendship_status, profile_context_facepile_users null Describe the viewer’s relationship to the account. The profile is read logged out, so they are always null
show_text_post_app_replies_tab, is_threads_only_user null Threads does not send them to a logged-out visitor
gating, text_app_custom_feeds, transparency_label, text_post_app_remove_mention_entrypoint null Always null for now

A fresh answer is shared across keys for 10 minutes (1 hour for a profile that does not exist). Only a 200 is charged. Asking again for a profile your key already paid for is free while it is cached, and resubmitting after a 503 never charges twice. A 403, 404, 429 or 503 is never charged.

Status When What to do
400 The handle is missing or not a valid Threads handle Fix the request
401 No API key, or an unknown one Check your key
402 Your balance cannot cover this plus your unfinished lookups, or the key’s own credit limit would be passed Buy credit or raise the key’s limit
403 Threads refused us, or served a page with no account in it (finishReason says which) Not charged. Do not retry blindly
404 No such profile (not-found), or the handle now leads to a different account, most likely a rename (handle-moved) Not charged
429 Rate limit, too many unfinished lookups, or this key has caused too many blocks or not-found lookups lately Slow down. Not charged
503 No answer in time, Threads failing, the service resting after repeated refusals, a login wall on every try (exit-walled), a page with only part of the profile (incomplete-profile), or the endpoint switched off Not charged. Resubmit after the Retry-After delay
Terminal window
curl -X POST "https://api.megomi.my.id/api/v1/threads/profile?handle=sportsillustrated" \
-H "x-api-key: YOUR_API_KEY"
{
"requestId": "req_9f1kQ3zP7mLxA2dR",
"handle": "sportsillustrated",
"status": "success",
"coalesced": false,
"cached": false,
"result": {
"pk": "63496592589",
"id": "63496592589",
"username": "sportsillustrated",
"full_name": "Sports Illustrated",
"biography": "Sports, sports and more sports.",
"text_app_biography": {
"text_fragments": {
"fragments": [
{ "fragment_type": "plaintext", "plaintext": "Sports, sports and more sports." }
]
}
},
"bio_links": [
{ "url": "https://lnk.bio/sportsillustrated", "is_verified": false, "link_id": "17882982429146262" }
],
"follower_count": 631664,
"is_verified": true,
"text_post_app_is_private": false,
"has_onboarded_to_text_post_app": true,
"show_text_post_app_badge": true,
"profile_pic_url": "https://scontent.example.invalid/1.jpg",
"hd_profile_pic_versions": [
{ "height": 320, "url": "https://scontent.example.invalid/2.jpg", "width": 320 },
{ "height": 640, "url": "https://scontent.example.invalid/3.jpg", "width": 640 }
],
"friendship_status": null,
"gating": null
},
"finishReason": "",
"success": true,
"credits_charged": 1,
"credits_remaining": 249
}