Submit asynchronous rank changes, check durable outcomes, and cancel unsent work safely.
Last updated
Asynchronous Roblox rank changes are available when shared scheduling is enabled for the deployment. Otherwise these resources return 503 scheduler_disabled. Existing rank endpoints retain their synchronous success responses.
Submit a rank change
Use POST /v2/roblox-operations/ranks with your Bearer API key, X-Clan-Id, and an Idempotency-Key. Submission requires members.ranks.write and Pro rank-management access.
http
POST /v2/roblox-operations/ranksAuthorization: Bearer YOUR_API_KEYX-Clan-Id: COMMUNITY_IDIdempotency-Key: promotion-player-123-attempt-1Content-Type: application/json{"userId":123,"roleId"
:
456
,
"expectedRoleId"
:
345
,
"deadlineSeconds"
:
300
}
Replace the sample values with the global Roblox user ID and the intended roles' unique IDs. roleId is the destination role; expectedRoleId is the role you expect the member to hold when the operation runs. These role IDs are different from numeric ranks such as 10 or 20. A queued operation cannot overwrite a later rank change when the expected role no longer matches.
Choose a stable key for one logical operation: 1–100 letters, digits, dots, colons, underscores, or hyphens. Repeating the same key and intent returns the existing operation. Reusing it for conflicting intent returns 409. Use a new key for a new intended action, and preserve the original key when retrying an uncertain submission.
The optional deadlineSeconds is 5–3600 seconds and defaults to 300. Repeating a submission does not extend its original deadline. Unsent work expires at that deadline; an already-sent request may need reconciliation afterward.
202 Accepted returns the operation ID, status, deadline, and status URL in data, plus a Location header. It confirms acceptance, not a completed Roblox rank change. Save the operation ID and poll its status. A 429 queue-full response means admission capacity is exhausted.
Waiting for dispatch; the rank change is not confirmed.
running
Processing is underway; the outcome is not confirmed.
reconciling
A sent request needs further outcome checks. Keep polling before another write.
completed
The intended result is confirmed.
failed
The operation ended with an error. Read its details and inspect current state before another action.
cancelled
Unsent work was cancelled.
expired
Unsent work reached its deadline.
Status and cancellation require the original enabled API key, its original operation permission, and current community/API access. They do not require an additional members.read scope. Another key or community cannot inspect the operation. Revocation or an ownership change can remove access.
Completed, failed, cancelled, and expired operations expire seven days after finalization. Database cleanup can briefly lag that cutoff. Active and reconciling operations are retained until their outcomes are finalized; passing a deadline does not delete an uncertain sent request. Save any final outcome your application needs for longer.
Cancel unsent work
Use DELETE /v2/roblox-operations/{id}. Check data.outcome: cancelled confirms cancellation, in-flight means a sent request cannot be retracted, and terminal means processing has already ended. Cancellation does not undo a completed Roblox change.
not-found means the record was unavailable when cancellation ran, possibly because finalized history was removed. It does not confirm that the request never ran or that cancellation succeeded. Verify the original ID and inspect the member's current Roblox state before submitting a replacement. A 404 response can also mean the ID is unavailable to your key or community.
Handle an uncertain synchronous result
Existing set-rank, promote, demote, and suspension routes do not switch to 202. When a sent request is unresolved, 504 outcome-pending-check-status includes X-Roblox-Operation-Id and a Location status path only when access to the operation can still be verified. Check the operation before repeating the write when a reference is returned. If access is revoked or cannot be verified, the pending result remains but the response omits the reference; inspect the member's current Roblox state before repeating the write.
When scheduling is disabled, a direct request timeout returns 504 roblox_cloud_timeout without an operation or status headers. Inspect the member's current Roblox state before repeating the write. If the original API key, required permission or community API switch is revoked before dispatch, 403 actor-authorization-revoked reports the local authorization change without an inaccessible status link.
AutoRank can also return this pending result from experience writes and forced profile refreshes, including legacy routes. The experience change may already be committed, so check the operation or reconcile the member's current state before repeating an increment. Event finishing reports accessible pending rank references in error.details.operations; the event and its awards have already committed. References can be omitted when access cannot be verified, so reconcile affected attendees' current Roblox state as well. Location and X-Roblox-Operation-Id identify only the first accessible reference. Repeating the finish cannot award points again.
If the synchronous deadline cancels an unsent operation, 409 deadline-cancelled-before-dispatch confirms it cannot execute later. See errors and rate limits for recovery guidance.
