Guides / End-to-end tutorials / Rare username checker & claimer A–Z
Rare username checker & claimer A–Z
Sweep 3–6 character, dictionary and brand @username candidates at 2 credits per check, filter out banned or trademark-reserved handles, verify 30-day handle cooldowns, and claim available handles onto an owned Connected Workspace account.
1. Separating truly claimable handles from banned / reserved handles
Checking whether a public profile 404s is not enough to know if a rare or short handle can be claimed: millions of 3–4 character, dictionary and brand handles have no public profile because they are banned, trademark-reserved, or inside TikTok’s post-rename quarantine window. Combining GET /v1/user/check-username (/aweme/v1/unique/id/check/, 2 credits) with POST /v1/user/bulk-check cleanly separates claimable handles from taken_active and reserved_or_banned handles before you touch a target session.
| Action | Endpoint | Cost |
|---|---|---|
| Check username | GET /v1/user/check-username | 2 cr |
| Bulk profile check | POST /v1/user/bulk-check | 5 cr / item |
| Get profile | GET /v1/user | 5 cr |
| Session health | GET /v1/account/health | 15 cr |
| Change username | POST /v1/account/profile/username | 25 cr |
| Update profile | POST /v1/account/profile/update | 25 cr |
2. High-speed candidate scanner + atomic Connected Workspace claimer
TypeScript SDKPython SDKMCP / cURLrare_username_claimer
1import { TikUltra } from 'tikultra'
2
3const client = new TikUltra({ apiKey: process.env.TIKULTRA_KEY, os: 'ios', appFlavour: 'tiktok', region: 'US' })
4
5export async function scanAndClaimHandle(candidates: string[], targetAccountId?: string) {
6 // 1. Batch-check public profile occupancy first to spot active vs non-existent handles
7 const bulk = await client.user.bulkCheck(candidates)
8 const occupied = new Set((bulk.data.items ?? []).filter((u: any) => u.exists).map((u: any) => u.username))
9
10 // 2. Run 2-credit mobile unique_id check on unoccupied candidates
11 const results = []
12 for (const raw of candidates) {
13 const handle = raw.replace(/^@+/, '').toLowerCase()
14 if (occupied.has(handle)) {
15 results.push({ handle, state: 'taken_active', alternatives: [] })
16 continue
17 }
18 const chk = await client.user.checkUsername(handle)
19 const claimable = Boolean(chk.data.is_available ?? chk.data.available)
20 results.push({
21 handle, state: claimable ? 'claimable' : 'reserved_or_banned',
22 alternatives: chk.data.recommended_unique_ids ?? chk.data.suggestions ?? [],
23 })
24 }
25
26 // 3. Optional: claim first available handle onto a staged caller-owned Connected Workspace account
27 const winner = results.find((r) => r.state === 'claimable')
28 if (winner && targetAccountId) {
29 const health = await client.account.health(targetAccountId)
30 if (!health.data.restricted) {
31 const claimed = await client.account.claimUsername(targetAccountId, winner.handle)
32 return { results, claimed: claimed.data }
33 }
34 }
35 return { results, claimed: null }
36}
2 credits per candidate + 30-day rename rule.
GET /v1/user/check-username is a Tier 1 primitive (2 credits — 1,000 handle checks cost 2,000 credits). Remember TikTok enforces a 30-day cooldown between @username changes on each account, so pre-stage a dedicated, warmed workspace account before claiming.