scapi

Look up Social Club account information through asynchronous callbacks.

These functions use Harmony's existing asynchronous Social Club service. They return results through callbacks on the script owner.

Social Club reference

scapi.available

Callback: None; checks lookup availability.

scapi.available()

Returns: Boolean

scapi.search_available

Callback: None; checks account-search availability separately.

scapi.search_available()

Returns: Boolean

scapi.name_to_rid

Callback: callback(result)

scapi.name_to_rid(name, callback)

Returns: Nothing

scapi.rid_to_name

Callback: callback(result)

scapi.rid_to_name(rid, callback)

Returns: Nothing

scapi.find_friends

Callback: callback(result); offset is required and zero-based.

scapi.find_friends(text, offset, callback)

Returns: Nothing

Names/search text must contain 1–50 bytes and no control bytes below 32 or byte 127. This is the service's input validation, not a guarantee that any matching Rockstar account exists. Rockstar IDs must be in 1..9,223,372,036,854,775,807; use decimal strings. Search returns at most 30 accounts per page and accepts an offset in 0..2,147,483,617.

Each script can retain up to eight requests awaiting delivery. The shared service processes one request at a time, so requests from this or another feature may return busy. Availability does not mean the service is idle. The implementation has a 30-second request timeout. There is no Lua request handle or cancellation method.

Result fields

Field	Type	Meaning
ok	Boolean	True only for scapi.status.success.
status	Integer	One of the status constants below.
rid	Decimal string	Lookup result ID; inspect ok first.
name	String	Lookup result name; inspect ok first.
total	Integer	Service-reported result total.
native_error	Integer	Underlying service error value, useful for diagnostics.
accounts	Array	Search result entries, each with name and decimal-string rid.

For account searches, read accounts; do not infer a successful single-account lookup from the top-level name or rid fields.

find_friends requires at least three characters and returns up to ten accounts per page through the installed Social Club overlay's search route. Its offset is a zero-based record index. Authentication comes from the native SDK; exact name/RID lookup still uses the native avatar interface. A failing search HTTP status is exposed through native_error.

Constant	Value	Interpretation
scapi.status.success	0	Request succeeded.
scapi.status.not_found	1	No matching account/result found.
scapi.status.invalid_input	2	Input failed validation.
scapi.status.busy	3	Shared service is already handling a request.
scapi.status.unavailable	4	Required service binding is unavailable.
scapi.status.failed	5	Request failed.
scapi.status.timed_out	6	Request exceeded its timeout.
scapi.status.cancelled	7	Service request was cancelled.
scapi.status.invalid_response	8	Returned data failed validation.

Lookup example

This example checks the local account's lookup status without publishing its identity:

local page = menu.root("Account lookup")
local pending = false

page:button("Check my account lookup", function()
    if pending then
        return
    end

    local me = players.local_player()

    if not me or me.rid == "0" or not scapi.available() then
        util.notify("Account lookup is unavailable")
        return
    end

    pending = true

    scapi.rid_to_name(me.rid, function(result)
        pending = false

        if result.ok then
            util.notify("Account lookup succeeded")
        elseif result.status == scapi.status.busy then
            util.notify("Account service is busy; try again later")
        else
            util.log("Lookup status: " .. tostring(result.status))
        end
    end)
end)

Do not issue a lookup every frame. Schedule bounded retries with script.after() if needed, and stop retrying when the relevant player or session changes.