Roblox operations
Submit asynchronous rank changes, check durable outcomes, and cancel unsent work safely.
Last updatedAsynchronous 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.
POST /v2/roblox-operations/ranks
Authorization: Bearer YOUR_API_KEY
X-Clan-Id: COMMUNITY_ID
Idempotency-Key: promotion-player-123-attempt-1
Content-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.
409 member-review-required means an earlier unresolved request protects this member and the new request was not submitted. Ask an authorised administrator to check Roblox operations; this error does not expose the earlier operation's metadata or status headers. 409 privacy-restricted also omits operation metadata and headers and blocks admission or replay while a data-rights restriction applies.
Read the outcome
Use GET /v2/roblox-operations/{id} or the returned Location.
| Status | Meaning |
|---|---|
queued | 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.
Read needsReview with the status, result, and error. It identifies an unresolved sent request that needs administrator review; it protects the affected member without occupying active queue admission. A failed or retired historical request does not establish that Roblox made no change. Automatic retirement preserves the current roles and leaves the original result unconfirmed.
Partial rank changes can enter managed automatic correction. Manual recovery follows the latest valid rank command; AutoRank uses current progression rules. Wait for recovery rather than submitting competing corrective writes. A current data-rights restriction can also block status or cancellation with 409 privacy-restricted, without operation metadata or status headers.
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.
Pending responses in service mode supply Retry-After: 2 for polling the authorised status URL with the same API key. This is a wait before the next status read, not permission to resubmit the mutation. Follow the actual response's interval and do not resubmit while the operation remains pending.
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.
With service-mode scheduling, an automatic rank check can reuse a still-active saved operation for the same community, authenticated API key and permission, member, and destination. Access is checked again before observing it. If that lookup is unavailable, Clan Labs does not submit a replacement as a fallback. This applies to automatic rank checks without an explicit idempotency key; it does not deduplicate XP changes, make all writes idempotent, or guarantee that simultaneous first submissions are combined. Manual rank submissions and workflow requests retain their own contracts.
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.
Handle maintenance
During a coordinated update, new rank and join requests can be paused while the API remains online. 503 roblox_maintenance currently supplies Retry-After: 5. Honor the response's actual retry interval. When retrying asynchronous rank submission, preserve the original Idempotency-Key for the same intent.
A maintenance refusal does not prove that an earlier ambiguous submission was never accepted. Reconcile the original operation or current Roblox state before replacing it. Keep this separate from scheduler_disabled, which means the asynchronous feature is unavailable for the deployment, and from an ordinary dependency failure.