Bulk jobs

A bulk job applies one operation to an explicit set of users or guilds. The task discriminator selects the payload contract, the Admin ACL evaluated for the request, and the worker task that runs.

Every target is a list of IDs. There is no search, role, tag, email, or IP selector, so the caller resolves its own target set first with List users or List guilds.

Queue bulk job returns a job identifier immediately and applies nothing synchronously. The caller reads progress, terminal state, and failure text through Get job. Cancel job stops a run.

Bulk job creation object

A bulk job creation has the identifier of the queued job.

Structure

Field	Type	Description
job_id¹	snowflake	The job that applies the requested operation, readable through Get job

¹ Fluxer writes the ledger row before it enqueues the job, so the identifier in a 200 is always readable

Example

{
  "job_id": "1501314428688998182"
}

Bulk task types

Each value is the exact task discriminator.

`update_user_flags`

ACL bulk:update:user_flags. Adds and removes account flags on every targeted user. Runs as bulkUpdateUserFlags.

`update_suspicious_activity_flags`

ACL bulk:update:suspicious_activity. Adds and removes verification requirements on every targeted user. Runs as bulkUpdateSuspiciousActivityFlags.

`update_guild_features`

ACL bulk:update:guild_features. Adds and removes features on every targeted guild. Runs as bulkUpdateGuildFeatures.

`add_guild_members`

ACL bulk:add:guild_members. Adds every targeted user to one guild. Runs as bulkAddGuildMembers.

`schedule_user_deletion`

ACL bulk:delete:users. Schedules account deletion for every targeted user. Runs as bulkScheduleUserDeletion.

Each worker task is recorded as task_type on the job and listed under background job task types. All five run in the lifecycle processing lane.

Queue bulk job

POST/v1/admin/bulk-jobs

Audit reason

Queues one bulk operation. Returns a bulk job creation object on success.

Limitations

The body matches exactly one task variant.
The caller needs at least one of the five bulk ACLs and then the exact ACL that task selects.

JSON body

The task discriminator selects one of these five structures. Every ID array has an upper bound and no lower bound, so an empty array queues a job that processes nothing and settles as succeeded.

Update user flags structure

Field	Type	Description
task	string	The discriminator selecting this variant, `update_user_flags`
user_ids	array[snowflake]	The users to update (max 1000 entries)
add_flags?¹	array[string]	Account flag values to add (max 64, default empty)
remove_flags?¹	array[string]	Account flag values to remove (max 64, default empty)

¹ Each entry is one 64-bit flag value as an unsigned decimal string, such as 1024, rather than a symbolic name. Additions are applied before removals, so a value named in both arrays ends up cleared

Update suspicious activity flags structure

Field	Type	Description
task	string	The discriminator selecting this variant, `update_suspicious_activity_flags`
user_ids	array[snowflake]	The users to update (max 1000 entries)
add_flags?¹ ²	array[string]	Suspicious activity flag names to add (max 32, default empty)
remove_flags?¹	array[string]	Suspicious activity flag names to remove (max 32, default empty)

¹ Each entry is the symbolic flag name such as REQUIRE_VERIFIED_PHONE. An entry naming no known flag is ignored, and additions are applied before removals

² Adding REQUIRE_VERIFIED_PHONE or REQUIRE_REVERIFIED_PHONE also clears the deferred phone bit 1 << 16, which turns a deferred phone requirement into an immediate one

Update guild features structure

Field	Type	Description
task	string	The discriminator selecting this variant, `update_guild_features`
guild_ids	array[snowflake]	The guilds to update (max 1000 entries)
add_features?¹	array[string]	Guild features to add (max 100, default empty)
remove_features?¹	array[string]	Guild features to remove (max 100, default empty)

¹ The boundary accepts any string, so a name outside the registry is written to the guild’s feature set. Additions are applied before removals

Add guild members structure

Field	Type	Description
task	string	The discriminator selecting this variant, `add_guild_members`
guild_id	snowflake	The guild that receives the users
user_ids	array[snowflake]	The users to add as members (max 1000 entries)

Schedule user deletion structure

Field	Type	Description
task	string	The discriminator selecting this variant, `schedule_user_deletion`
user_ids	array[snowflake]	The users to schedule for deletion (max 1000 entries)
reason_code	integer	Deletion reason recorded against every targeted account
public_reason?	string	The reason shown to each account holder in the deletion notice (0-512 characters after normalisation)
days_until_deletion?¹	integer	The delay before deletion in whole days (1-365, default 60)

¹ Fluxer raises the value to the reason-specific minimum, 14 days for USER_REQUESTED and 60 days for every other code

Response

Status	Body	Condition
200	bulk job creation object	The bulk job was queued
403	error response	`MISSING_ACL` without the ACL selected by `task`
500¹	error response	The job could not be queued

¹ A full queue rejects the job, which surfaces as INTERNAL_SERVER_ERROR

The 200 confirms that the job was queued. Get job reports whether its mutations completed.

Side effects

This operation writes no Admin audit entry. It records one Jobs ledger row naming the acting Admin as the requester and storing the audit reason, then enqueues the worker task. When the ledger row cannot be written, Fluxer returns 500 INTERNAL_SERVER_ERROR and enqueues nothing.

The worker processes entities in the submitted order, one at a time. A cancellation check runs before each entity, so Cancel job stops the run between two entities and settles the job as cancelled. Every entity changed before cancellation or failure stays changed. An entity that fails, including an ID that resolves to nothing, is counted as failed and skipped, and the run continues through the rest of the set. The worker reports progress before the run starts, after every 25 entities, and once at the end. schedule_user_deletion reports after every 10 accounts instead. The closing progress message has the successful and failed counts.

Every task writes one summary Admin audit entry when it finishes, with the action bulk_update_user_flags, bulk_update_suspicious_activity_flags, bulk_update_guild_features, bulk_add_guild_members, or bulk_schedule_deletion. The summary has the audit reason, the entity count, the operation-specific parameters, and the successful and failed counts. Its target_id is the guild for add_guild_members and 0 for the four tasks that target a set. A cancelled or failed job writes no summary entry.

Updating account flags writes one update_flags entry for each account and dispatches User Update to the account’s sessions. A change to a publicly visible flag also dispatches Guild Member Update to every guild the account is in.

Updating suspicious activity flags rewrites each account’s verification requirements and dispatches User Update. No Guild Member Update follows. The task writes no per-account audit entry.

Updating guild features writes one update_features entry for each guild, dispatches Guild Update, and reindexes the guild for search. Fluxer reconciles a guild that already has a discovery application record against the new feature set, so gaining DISCOVERABLE approves the record and losing it marks the record removed. A guild with no discovery record is left alone.

Adding guild members bypasses the ban check and the risk gate. The task suppresses the join system message, records the join source as an Admin force add, and dispatches Guild Member Add to the guild and Guild Create to the added account’s sessions. The task still enforces the per-account guild cap and the guild member cap, so an account at either ceiling is counted as failed. An account that is already a member is left unchanged and counted as successful, with no second membership and no Dispatch. Adding a bot account also records a BOT_ADD guild audit log entry attributed to the acting Admin.

Scheduling deletion marks each account deleted. The task stores the reason code, public reason, and audit reason on the account, and reschedules its pending deletion. It dispatches User Update, writes one schedule_deletion entry for each account, and emails the account holder when an address is on file. A failed email is logged and does not fail the entity.

Rate limit

20 requests per minute for each authenticated user, on the admin:bulk:operation bucket.