How to Use the FriendPath API in Your Own Roblox Tool or Game

Two APIs, two access models

FriendPath publishes two separate public APIs with different policies:

• Scan API — the powerful one. Runs a full bidirectional BFS through Roblox's friend graph and returns the shortest path. Hosted on arbastro.com. Requires an API key. Metered.
• Famous Users API — the lightweight one. Returns a JSON list of ~3,800 notable Roblox accounts (creators, YouTubers, devs). Hosted on friendpath.arbastro.com. Free for everyone, no key.

If you want to do a path lookup, you need the Scan API and a key. If you just want a list of famous accounts (e.g. for a dice/randomizer in your own tool), the Famous Users API is enough.

Getting an API key

1. Sign up for an arbastro account if you don't already have one
2. Subscribe to arbastro Suite ($4.99/mo or $4.17/mo annual, 30-day free trial). Suite includes 50 free Scan API calls per day + $0.005 per call beyond.
3. Go to arbastro.com/account/api-keys and click Create key
4. Copy the key (starts with ak_live_). It's shown to you exactly once — save it somewhere secret like an env var or a Roblox studio secret

The Scan API endpoint

Single GET, returns JSON. The API key goes in the Authorization header as a Bearer token.

GET https://arbastro.com/api/v1/friendpath/path
  ?from=YourUsername
  &to=TargetUsername

Authorization: Bearer ak_live_YOUR_KEY

Example with curl:

curl "https://arbastro.com/api/v1/friendpath/path?from=Builderman&to=david.baszucki" \
  -H "Authorization: Bearer ak_live_YOUR_KEY"

Response shape on a successful path:

{
  "from": { "input": "Builderman", "userId": 156 },
  "to":   { "input": "david.baszucki", "userId": 5208617297 },
  "result": {
    "type": "done",
    "degrees": 2,
    "visited": 14328,
    "path": [
      { "id": 156, "name": "Builderman", "displayName": "Builderman" },
      { "id": 12345, "name": "SomeIntermediate" },
      { "id": 5208617297, "name": "david.baszucki", "displayName": "David Baszucki" }
    ]
  }
}

When no path exists, result is null and a reason field describes why (private friend list, banned account, UK-restricted, depth exceeded, etc.).

Using it from Roblox Lua

From inside a Roblox game, use HttpService:RequestAsync so you can set the Authorization header (the simpler GetAsync doesn't let you set headers). Note that HttpService.HttpEnabled must be true on the place — only the place owner can enable this.

local HttpService = game:GetService("HttpService")

local FRIENDPATH_KEY = "ak_live_YOUR_KEY"  -- store this in a secret, not in source

local function getFriendPath(fromUser, toUser)
    local url = string.format(
        "https://arbastro.com/api/v1/friendpath/path?from=%s&to=%s",
        HttpService:UrlEncode(fromUser),
        HttpService:UrlEncode(toUser)
    )
    local ok, response = pcall(function()
        return HttpService:RequestAsync({
            Url = url,
            Method = "GET",
            Headers = {
                ["Authorization"] = "Bearer " .. FRIENDPATH_KEY,
            },
        })
    end)
    if not ok then return nil, response end
    if not response.Success then return nil, response.StatusCode end
    local ok2, parsed = pcall(HttpService.JSONDecode, HttpService, response.Body)
    if not ok2 then return nil, parsed end
    return parsed.result, nil
end

local result, err = getFriendPath("Builderman", "david.baszucki")
if result then
    print(string.format("%d degrees of separation", result.degrees))
end

Using it from JavaScript / Node.js

const url = new URL("https://arbastro.com/api/v1/friendpath/path");
url.searchParams.set("from", "Builderman");
url.searchParams.set("to", "david.baszucki");

const resp = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.FRIENDPATH_KEY}` },
});
const data = await resp.json();
if (data.result) {
  console.log(`degrees: ${data.result.degrees}`);
} else {
  console.log(`no path: ${data.reason}`);
}

Using it from Python

import os, requests

resp = requests.get(
  "https://arbastro.com/api/v1/friendpath/path",
  params={"from": "Builderman", "to": "david.baszucki"},
  headers={"Authorization": f"Bearer {os.environ['FRIENDPATH_KEY']}"},
)
data = resp.json()
if data.get("result"):
    print(f"{data['result']['degrees']} degrees")
else:
    print(f"no path: {data.get('reason')}")

The Famous Users API (free, no key)

Separate endpoint, separate host, free for everyone. Returns the snapshot of ~3,800 notable Roblox creators we use for the dice button on the main site.

curl "https://friendpath.arbastro.com/api/famous-users"

Response is a JSON array of objects with id, name, displayName, hasVerifiedBadge, etc. No authentication, but please don't hammer it — it's rate-limited per IP to keep it free for everyone. The dataset is regenerated periodically; expect minor changes over time.

What to build with it

• "Find your six degrees" Roblox game — let players input a target and watch the search animate in-game
• Discord bot — /friendpath user1 user2 returns the path in chat. We have a full tutorial
• Leaderboard of "who is closest to X celebrity" — for creator communities, fan groups, etc.
• Friend overlap visualizer — combine with Roblox's own /users/{id}/friends endpoint
• Stream overlay — for Roblox streamers, show "degrees from KreekCraft" as a viewer chat command

Errors you'll see

• 401 — missing or invalid api key / api key revoked. Check the header is Authorization: Bearer ak_live_... and the key hasn't been deleted
• 402 — billing required. You've used your 50 free daily Scan calls and don't have a payment method on file
• 429 — per-key rate limit hit. Back off a few seconds and retry
• 422 — bad usernames (not found on Roblox)

Rate limits

Suite subscribers get 50 free Scan calls per day. Beyond that, calls are metered at $0.005 each (billed monthly through Stripe). There's also a per-key rate limit of a few calls per second to prevent runaway loops. The Famous Users API has IP-based rate limits but no per-call cost.

One caveat: UK accounts

The API has the same UK Online Safety Act limitations as the main site — British accounts have hidden friend lists at Roblox's level, and there's nothing the API can do about that. If you're building something that needs to handle UK users, surface a workaround note (see our UK Online Safety Act post) so they can search starting from a non-UK friend instead.

Full reference + try-it-out

Detailed parameters, all endpoints, error codes, and an in-browser request runner are on the docs page: friendpath.arbastro.com/docs. You can fire off live API calls from the docs page with your key — useful for testing before you write code.