Most creator identity work is guesswork. You have an Instagram handle and you want the same person on TikTok, YouTube and Spotify, so you try the handle on each platform and hope.
A Linktree page is the one place where the creator already answered the question. They listed their accounts themselves, and usually a contact address with them. Reading that page is more reliable than any amount of matching, because it is declared rather than inferred.
This guide covers GET /v1/linktree/profiles/{handle}: what comes back, how to use it as a resolution step in a creator pipeline, and what the page ordering tells you about what someone is currently pushing.
You'll need an API key and curl or the TypeScript SDK. New to the API? Start with the Quickstart.
The one place identity is declared
The usual approach to cross-platform creator matching runs on inference. Try the handle everywhere, compare avatars, look for the same links in bios, score the candidates. It works often enough to be useful and it is wrong often enough to need review. Cross-platform creator profiles walks through that pipeline properly.
A link-in-bio page skips the inference. The creator sat down and attached their own accounts. When a Linktree exists, it is the highest-confidence source you will find, and it costs one lookup instead of one per platform.
The catch is coverage. Not every creator has a Linktree, and the ones who do are weighted toward music, fashion, fitness and anyone who sells something. Treat it as a fast path that resolves a good fraction of your list, then fall back to inference for the rest.
Read a profile
The handle is the path segment. A leading @ is accepted and stripped.
A real response, trimmed:
One credit, one call, and you now hold five platform identities and a working contact address for a creator you previously knew by a single handle.
In the SDK:
A handle that does not exist returns lookupStatus: "not_found" with profile: null and empty arrays, and it still bills one credit. Check the status, do not check for an HTTP error.
Handles almost never match
Look again at the socials array above. The Linktree handle is miguelangeles. The TikTok handle is @irlangel.
That is the whole argument for this endpoint in one line. A pipeline that took miguelangeles and tried tiktok.com/@miguelangeles would have found nothing, or worse, found a different person and attached their metrics to the wrong creator.
Handles diverge for ordinary reasons. Good names get claimed early on the older platforms, so people register a variant on the newer ones. Artists have a project name and a personal name. Brands split by region. None of it is unusual, and all of it breaks same-handle matching quietly, which is the dangerous kind of breakage because nothing errors.
Same-handle matching fails silently
The failure mode is not an empty result. It is a populated result for the wrong person. If you match by handle without verification, budget for a human review step, or resolve from a declared source like this one first.
What the links array tells you
The socials array is identity. The links array is intent.
Each entry carries a type label that tells you what the destination is without parsing the URL: SPOTIFY_ALBUM, SPOTIFY_SONG, YOUTUBE_VIDEO, SOUNDCLOUD_PLAYLIST, and CLASSIC for a plain link with no special treatment. The label comes from Linktree's own link editor, so it reflects what the creator chose the block to be.
That is more useful than it first looks. The mix of types is a rough read on what someone does. A page that is mostly SPOTIFY_SONG belongs to a musician. A page of CLASSIC links to a Shopify store and a discount code belongs to someone selling. You can segment a list of thousands of creators on link types alone, before spending a credit on any platform metrics.
Position is the creator's priority
Every link has a position, and it is the creator's own ordering. Position 0 sits at the top of the page, which is the slot they gave to whatever they most want people to click this week.
Note the positions in the response above: 0, 1, 2, 3, 5, 6, 7. There is no 4. Positions are not a dense index, because hidden, scheduled and deleted blocks leave gaps. Sort by position rather than trusting array order to be contiguous, and never treat the value as an array index.
Building a creator resolution step
The pattern that works is Linktree first, inference second.
Start from wherever your creators come from, usually an Instagram or TikTok profile whose bio contains a linktr.ee URL. Pull the handle out of that URL. Resolve it here. Write the declared socials into your creator row and mark them high confidence. For anyone without a Linktree, fall back to the handle-matching pipeline and mark those rows for review.
Keeping a source column matters more than it looks. Six months later, when someone asks why a creator's YouTube channel is wrong, the difference between "they told us" and "we guessed" is the first thing you want to know.
The email is the other reason teams run this. Creator outreach usually stalls on contact details, and a mailto: the creator published on their own page is the cleanest version of that data you can get. Read the FAQ note on outreach before you load it into a sending tool.
Watching what a creator promotes
Because position reflects current priority, the same lookup run on a schedule becomes a campaign detector.
Store the top few links per creator per run, keyed on link id. Then watch for a new id appearing at position 0, an existing link moving up, or a link disappearing entirely. A new top link is usually a launch: a single, a drop, a collaboration, a sponsor. It typically appears on the page before the creator posts about it, because they stage the link first and then start driving traffic to it.
For a brand tracking its own sponsorships, this answers a question that is otherwise awkward to ask: is the creator we paid actually still linking to us, and where on the page did we end up? A partner link that quietly slid from position 0 to position 9 is worth knowing about.
Monitors and webhooks cover running checks on a schedule and getting pushed the changes rather than diffing snapshots yourself.
Limits worth knowing
Lookup only, no search. You need a handle. There is no keyword index and no way to list creators by category, so discovery has to start on a platform that does have search.
Linktree specifically. Beacons, Komi, Stan and the rest are not covered by this route. For those, the web extraction routes can fetch and parse a page, but you get generic content instead of typed links and a structured socials array.
Declared, not verified. Linktree does not check that the TikTok URL a creator attached is really theirs. It is far better evidence than a handle guess, and it is still a claim rather than a proof. Impersonation pages exist.
No metrics. You get identity and links, not follower counts or engagement. Fan out to the platform endpoints for numbers, which is exactly the point of resolving the identities first.
Pages change without notice. The link a creator promoted last week may be gone. If the history matters to you, store each run rather than overwriting.
FAQ
What does the Linktree endpoint return?
Three things: a profile block with display name, bio, avatar and verified flag; a links array of everything on the page with title, destination URL, type label, thumbnail and position; and a socials array of the platform icons the creator attached, which often includes a contact email as a mailto: link.
Can I search Linktree for creators by keyword?
No. The route is a lookup by handle, not a search index. For discovery, start from a platform search endpoint such as Instagram or TikTok profile search, take the linktr.ee URL out of the bio, and resolve the handle from there.
Why does the Linktree handle differ from the creator's other handles?
Because they are registered separately and good handles get taken. A creator can hold linktr.ee/miguelangeles while posting on TikTok as @irlangel. This is the normal case, which is exactly why reading declared socials beats guessing the same handle everywhere. See handles almost never match.
Does a failed lookup still cost a credit?
Yes. Credits charge when a lookup completes, and not_found is a completed lookup returning lookupStatus: "not_found" with a null profile. Check lookupStatus rather than assuming HTTP 200 means data arrived, and reconcile against meta.creditsCharged.
Does this cover Beacons, Komi, or other link-in-bio services?
Not through this route, which reads Linktree specifically. For other services the web extraction routes can fetch and parse a page, though you get generic page content rather than the typed structure this endpoint returns.
Is the email in socials safe to use for outreach?
It is a business contact the creator chose to publish on a public page, which is the usual basis for creator outreach. You remain responsible for GDPR, CAN-SPAM, PECR and anything else that applies to you, including honouring opt-outs. Publishing an address is not consent to bulk mail, so treat it as a lead rather than a list. This is not legal advice.
How fresh is the data?
Each request reads the live page at call time, with no cached snapshot. If a value looks wrong, meta.requestId lets support trace that specific lookup.
How does this compare to other providers?
See the side-by-side comparisons: vs Modash, vs Phyllo, vs Apify, and the full compare hub.
Next steps: Linktree endpoint reference · Cross-platform creator profiles · Monitors and webhooks · Quickstart · Pricing