Threads Creator Research API Tutorial

Read a known Threads profile or search candidate accounts with one request. Validate responses, preserve unknown metrics, and review candidates before choosing.

Dark cinematic render of a list of Threads handles resolving into ranked profile cards feeding an agent core

A known Threads handle and a brand name are not the same input. If you already know the account, read that profile directly. If you have only a name or topic, search for candidates and review them before choosing one. This Threads creator research API tutorial implements those two first requests without turning a loose match into an automatic account selection.

On 2026-11-08, this repair checked free endpoint inspection and the current public reference responses. It did not execute a paid Threads business request. The original 2026-09-27 UTC profile capture remains below, with its run ID and values intact. For the wider endpoint map, see the Threads public data API hub; the current implementation here stops after one profile or one candidate-search response.

Key takeaway

  • Known handle: threads/web/user-info accepts username and returns a business payload with a user object.
  • Candidate discovery: threads/web/search-profiles accepts query; candidate objects are under xdt_api__v1__users__search_connection.edges[].node.
  • Both read only the documented outputs[0].data envelope. Missing structures are errors, not empty profiles or zero followers.
  • No automatic first-match choice, handle loop, ranking, post fetch, retry or pagination is included.

Choose your Threads creator research API input

What you haveRequestWhat to review
An already confirmed handleUser ProfileThe profile returned for that username
A brand name, display name or search phraseProfile SearchA set of candidate accounts, not a selected identity

The profile request schema has one required string, username; the search schema has one required string, query. Neither declares page, cursor, end_cursor or limit. Do not transplant a posts endpoint’s pagination parameters into either request. There is no supported “keep searching the next page” loop in this example.

For a profile link such as https://www.threads.net/@nasa, the API input is the username nasa, not the full URL or a numeric account ID. The helper accepts a bare handle or one leading @, trims surrounding whitespace, and checks a simple letters/digits/dots/underscores format. That is a local input guard, not a complete claim about every upstream username rule. It does not establish that the account exists.

Search is deliberately broader. The public reference warns that similar handles can appear alongside the intended brand. A matching display name or a verified flag does not, by itself, identify the organization you meant. Review the returned username against the account you intended to research before requesting more information. The code returns all candidate nodes unchanged and never picks the first one.

Connect your existing project or agent

Already have a key? Reuse the project’s local SANDBASE_API_KEY or its existing secret store. Already connected your agent to SandBase? Reuse that connection and inspect the selected endpoint instead of creating another key. For a new project, give your agent the setup skill and Markdown quickstart, then describe your task and provide the handle or query. The API key stays out of prompts and generated source files.

A useful task description is: “Use my SandBase connection to inspect threads/web/search-profiles, then make one query for the name I provide. Show the candidates for review. Do not pick an account, fetch every profile, rank by followers or read posts.” For a known handle, replace the task with a single user-info request. Agreeing on that stopping point prevents a small lookup from becoming a larger research job without review.

For Python, install requests with python3 -m pip install requests. Save the example as first_request.py, set the key locally, then run python3 first_request.py. The main block reads the known example handle nasa once. To search instead, replace the last two lines with result = first_request("search", "OpenAI") and print("Candidate count:", len(result[SEARCH_CONNECTION]["edges"])). These are alternative tasks, not two calls to concatenate.

A single request with endpoint-specific validation

Use the Model API POST route shown in the endpoint README: https://api.sandbase.ai/v1/api/threads/web/<operation>. The body contains only username or query. The catalog GET surface and generic /v1/run entries embedded in an upstream schema are not substitutions for this documented per-endpoint request.

Python
import os
import re
import requests

SEARCH_CONNECTION = "xdt_api__v1__users__search_connection"


def first_request(task, value):
    if not isinstance(value, str) or not value.strip():
        raise ValueError("Provide a known username or a search query")
    value = value.strip()
    if task == "profile":
        username = value[1:] if value.startswith("@") else value
        if not re.fullmatch(r"[A-Za-z0-9._]+", username):
            raise ValueError("Use a username, not a profile URL")
        path, params = "user-info", {"username": username}
    elif task == "search":
        path, params = "search-profiles", {"query": value}
    else:
        raise ValueError("Choose profile or search")
    key = os.environ.get("SANDBASE_API_KEY", "").strip()
    if not key:
        raise RuntimeError("Set SANDBASE_API_KEY locally")
    try:
        response = requests.post(
            f"https://api.sandbase.ai/v1/api/threads/web/{path}",
            headers={"Authorization": f"Bearer {key}"}, json=params,
            timeout=(10, 90), allow_redirects=False,
        )
        if not 200 <= response.status_code < 300:
            raise RuntimeError(f"SandBase HTTP {response.status_code}")
        body = response.json()
    except ValueError:
        raise RuntimeError("SandBase returned invalid JSON") from None
    except requests.RequestException:
        raise RuntimeError("SandBase network request failed; not retried") from None
    if not isinstance(body, dict) or body.get("status") != "completed":
        raise RuntimeError("SandBase request did not complete")
    outputs = body.get("outputs")
    if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
        raise RuntimeError("Missing documented outputs[0].data")
    payload = outputs[0].get("data")
    if not isinstance(payload, dict):
        raise RuntimeError("Missing documented outputs[0].data")
    if task == "profile":
        user = payload.get("user")
        if not isinstance(user, dict) or not user:
            raise RuntimeError("Missing or empty Threads user object")
    else:
        connection = payload.get(SEARCH_CONNECTION)
        if not isinstance(connection, dict) or not isinstance(connection.get("edges"), list):
            raise RuntimeError("Missing Threads search connection/edges array")
        for edge in connection["edges"]:
            if (not isinstance(edge, dict) or not isinstance(edge.get("node"), dict)
                    or not edge["node"]):
                raise RuntimeError("Missing or empty Threads search node object")
    return payload


if __name__ == "__main__":
    result = first_request("profile", "nasa")
    print("Profile name:", result["user"].get("full_name"))

The two business structures differ even though the SandBase envelope is shared. Profile requires a nonempty user object. Search requires the named connection object, an edges array and a nonempty object in each edge’s node. An empty edges array is valid; a missing array is not. Rejecting empty profile/node objects is a local completeness guard so that the example does not print an unusable record as a successful lookup.

Neither public reference response needs a provider code: 0 or success: true rule, so the helper does not add one. An HTTP error, failed or unfinished run, malformed JSON, old top-level output, missing user or missing search structure stops execution. It does not swallow an upstream error as “no candidates.” The returned payload remains unchanged; optional business fields are not filled in.

Requests use a connection/read timeout and do not follow redirects. A timeout, network error or 401/402/403/429/5xx response triggers no automatic retry. Errors contain neither the authorization header nor the raw provider body. Check credentials, account billing context or rate limits as appropriate before deciding on another attempt. Mock tests verify these client decisions; they do not prove current provider availability.

Interpret profiles and candidates without manufacturing a ranking

The current public profile reference shows NASA with a display name, biography, follower count, verified flag and an empty bio_links list. Those are fields observed in that published example, not values freshly measured by this repair or a promise that every record includes them. Optional fields can be missing or null. An absent follower_count is unknown, while an explicit numeric zero is a returned value; combining them destroys information.

Likewise, do not turn an absent is_verified into false. “Not supplied” and “supplied as false” are different research states. If you later build a table, retain unknown values and the retrieval date before choosing comparison rules. Follower count is a profile metric, not a measurement of post reach, campaign performance or audience quality.

The public search sample contains account identity fields under node, including username, full_name, id, pk and is_verified. It does not establish a follower-count field for every search candidate. A search-result list therefore cannot be silently fed into the old follower ranking. Keep the candidate set as candidates; deciding whom to inspect is a separate task.

The profile reference’s empty bio links also do not establish how every nonempty link item will be structured. Inspect a real returned item before writing a mapper. Reading a link or profile-picture URL in JSON does not fetch that destination; the example does not download pictures or follow bios. It also makes no claim to read private account content.

Price and free-quota eligibility

Free inspection on 2026-11-08 lists a $0.002 base price for a profile lookup and $0.003 for profile search. Both advertise eligibility for the organization’s 100 daily calls shared across eligible data APIs, resetting at 00:00 UTC. This update did not query the remaining allowance or execute a business call. Eligibility is not proof that your next request will be free.

Before any applicable allowance, the chosen single lookup is budgeted at its listed price. Searching once and then reading one manually selected profile would be two separate requests, with a combined base estimate of $0.005 at these prices. That is planning arithmetic, not a workflow the example executes or a measured charge. A larger handle list needs its own budget and error accounting.

Historical profile experiment, 2026-09-27

The original tutorial resolved handles and sorted flat rows. Its verbatim bilingual Python archive preserves all eight original blocks with source-commit and SHA256 records. That code skipped missing profiles, replaced missing follower counts with zero, defaulted verification to false and looped over a handle list. It is retained for provenance, not current execution guidance. The old cover’s ranked cards are a conceptual illustration, not a tested creator leaderboard.

Historical SandBase Threads API catalog listing Historical catalog screenshot, 2026-09-27. It shows the endpoint listing, not a successful profile or search run; current input and price evidence was checked separately.

The original user-info capture for zuck used run 77059cb9-8616-4be1-abfe-96e82a12b54f. The following JSON is retained unchanged. Its follower count and bio are point-in-time historical observations, not current values:

JSON
{
  "id": "77059cb9-8616-4be1-abfe-96e82a12b54f",
  "status": "completed",
  "model": "threads/web/user-info",
  "outputs": [
    {
      "data": {
        "user": {
          "full_name": "Mark Zuckerberg",
          "biography": "Mostly superintelligence and MMA takes",
          "follower_count": 5744972,
          "is_verified": true,
          "bio_links": [],
          "id": "63055343223",
          "pk": "63055343223"
        }
      }
    }
  ]
}

Historical Threads User Info API reference Historical user-info parameter/reference screenshot, 2026-09-27. The actual historical profile sample is the JSON above; the screenshot is not a fresh business execution.

The old list named zuck, mosseri and natgeo; this article preserves one explicit profile response, not separate evidence that every listed account returned the same fields. The old sort also used (verified, followers) with descending order, so verification was the primary sort key. It was not simply “rank by reach.” Missing counts and flags made that ranking especially difficult to interpret. The new example removes the sort rather than dressing it up as an audited comparison.

Historical Threads User Info by ID API reference Historical user-info-by-id parameter reference, 2026-09-27. This is a different endpoint from username lookup and was not revalidated in this repair.

FAQ

Do I need a Threads or Meta login? The two current request schemas use SandBase authentication and do not request a Threads login cookie or OAuth token. They do not grant access to private or account-authorized content.

Why fail when a profile is missing? A missing, null or empty user object is not a confirmed profile with zero followers. The helper reports the problem so it stays separate from a valid response with optional fields missing.

Can I select the first search result? The helper will not. Search can include similar accounts; review the username and intended identity before selecting any candidate for a separate request.

How do I request more candidates? The inspected search schema declares only query. Do not invent page, cursor or limit fields. This update does not claim complete search coverage or a validated continuation mechanism.

Can I continue to posts and replies? Those are separate endpoints and tasks. This repair did not verify their current availability, pricing, identifiers or pagination; inspect them before extending the workflow.

Start with the input you actually know, inspect one response, and keep unknown fields visible before deciding what further research is justified.

Found this useful? Share it