How do I get an Instagram user ID from a username?
Call the Openhandle profile endpoint with @username. The response carries the platform ID in data.id. That is the same numeric ID Instagram uses internally. It never changes, even when the account renames.
Store the ID next to the username on first contact. Every later call can use the ID instead. A renamed account still resolves. A username that was reassigned to someone else does not fool you.
Checked September 2026 · request and response run against the API · no affiliate links
curl "https://api.openhandle.dev/v1/instagram/profiles/@northstar_forge_test" \
-H "Authorization: Bearer $OPENHANDLE_API_KEY"import { OpenHandle } from '@openhandle/sdk';
const openhandle = new OpenHandle({ apiKey: process.env.OPENHANDLE_API_KEY! });
const { data } = await openhandle.instagram.profile('northstar_forge_test').get();
console.log(data.id); // "910000000001"
const later = await openhandle.instagram.profile({ id: data.id }).get();{
"platform": "instagram",
"resource": "profile",
"capturedAt": "2026-09-18T11:20:05Z",
"source": "live",
"data": {
"id": "910000000001",
"handle": "northstar_forge_test",
"url": "https://www.instagram.com/northstar_forge_test/",
"displayName": "Northstar Forge"
}
}Trimmed to the identity fields. IDs are strings in the API even though Instagram’s are numeric, so a large ID never loses precision in JavaScript. The example is a Test account.
Why the ID matters
- —Usernames move. An account can rename. Instagram can hand the old name to someone else after a while. A tracker keyed on the name silently switches accounts.
- —IDs are stable. The platform ID stays with the account for its whole life. Openhandle also keeps an identity index that maps old handles to IDs for a year.
- —Same rule on every platform. TikTok, X, and Reddit profiles carry
data.idin the same place. Store it the same way.
From a URL
If you start with a profile URL, pass it to POST /v1/urls/fetch or openhandle.fetch(url). It returns the profile with its ID. The SDK can also parse the username out of the URL locally before calling.
When this does not work
These answers are definitive. Store them, do not retry them.
| Situation | Status | Code |
|---|---|---|
| The account is private | 403 | PROFILE_PRIVATE |
| The username does not exist | 404 | PROFILE_NOT_FOUND |
| The username is malformed | 400 | INVALID_IDENTIFIER |
{
"error": {
"code": "PROFILE_NOT_FOUND",
"message": "This profile was not found.",
"requestId": "req_01j8…",
"retryable": false
}
}A private account still has an ID, but Openhandle does not read private profiles, so the lookup answers PROFILE_PRIVATE with no data.
Read next
More Instagram questions
Send your agent ahead.
Paste the prompt into your agent and it sets everything up. Or come yourself, it takes five minutes.