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.
Endpoint
Section titled “Endpoint”| Method | Path | Returns |
|---|---|---|
| POST | /api/v1/threads/profile |
A public Threads profile |
Request & Response
Section titled “Request & Response”Request
Section titled “Request”| 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 |
handleis the only accepted identifier. A profile URL or a numeric user id is a400.- A handle with a space or
-, one made only of dots, or one longer than 30 characters is a400.
Response body
Section titled “Response body”| 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 |
The result object
Section titled “The result object”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 |
Caching and cost
Section titled “Caching and cost”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.
Errors
Section titled “Errors”| 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 |
curl -X POST "https://api.megomi.my.id/api/v1/threads/profile?handle=sportsillustrated" \ -H "x-api-key: YOUR_API_KEY"const params = new URLSearchParams({ handle: "sportsillustrated" });const res = await fetch(`https://api.megomi.my.id/api/v1/threads/profile?${params}`, { method: "POST", headers: { "x-api-key": process.env.MEGOMI_API_KEY }, signal: AbortSignal.timeout(60_000),});const data = await res.json();import requests
res = requests.post( "https://api.megomi.my.id/api/v1/threads/profile", params={"handle": "sportsillustrated"}, headers={"x-api-key": "YOUR_API_KEY"}, timeout=60,)print(res.json())<?php$url = "https://api.megomi.my.id/api/v1/threads/profile?" . http_build_query(["handle" => "sportsillustrated"]);$ch = curl_init($url);curl_setopt($ch, CURLOPT_POST, true);curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY"]);curl_setopt($ch, CURLOPT_TIMEOUT, 60);curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);echo curl_exec($ch);q := url.Values{}q.Set("handle", "sportsillustrated")req, _ := http.NewRequest("POST", "https://api.megomi.my.id/api/v1/threads/profile?"+q.Encode(), nil)req.Header.Set("x-api-key", "YOUR_API_KEY")client := &http.Client{Timeout: 60 * time.Second}resp, _ := client.Do(req){ "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}{ "status": 400, "title": "Bad Request", "detail": "handle is required" }{ "status": 404, "title": "Not Found", "detail": "the source reports no such profile (deleted, or never existed); you were not charged. This answer is cached for an hour", "requestId": "req_9f1kQ3zP7mLxA2dR", "finishReason": "not-found"}{ "status": 503, "title": "Service Unavailable", "detail": "no data fetched within 45s; you were not charged. The lookup is still running: submitting the same request again shortly may return it from cache, and is never charged twice", "requestId": "req_1qLr6PxV8nWtE3sJ", "finishReason": "no-data-fetched"}