Jobs
These routes list recorded background jobs and request cancellation. Create jobs through Queue bulk job, Create system DM broadcast, Refresh search index, or an archive request.
Reads require jobs:view and cancellation requires jobs:cancel. Every operation on this page shares the admin:jobs:view bucket. The three reads record no Admin audit entry, and cancellation records one.
Admin job object
Section titled “Admin job object”One object describes one recorded job. These routes can only change cancel_requested.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| job_id | snowflake | The ID of the job |
| task_type | string | The background job task type the job runs |
| status | string | The latest recorded job status |
| progress_current | ?integer | The units of work reported as complete, or null |
| progress_total | ?integer | The reported total units of work, or null |
| progress_message | ?string | The latest reported progress message, or null |
| error_message | ?string | The recorded failure reason, or null |
| created_at | ISO8601 timestamp | The time the job was recorded |
| started_at | ?ISO8601 timestamp | The latest recorded start time, or null when no start was recorded |
| completed_at | ?ISO8601 timestamp | The recorded completion, cancellation or failure time, or null |
| requested_by_user_id | ?snowflake | The recorded requester, or null |
| audit_log_reason | ?string | The recorded audit log reason, or null |
| jet_stream_lane | ?string | The assigned processing lane, or null |
| jet_stream_seq | ?string | The recorded queue sequence as a decimal string, or null |
| attempts | integer | The recorded retry count, not a total of all executions |
| max_attempts | integer | Attempt limit recorded at queue time. Retries stop at the lane’s delivery limit, which can differ from this value |
| run_at | ?ISO8601 timestamp | The earliest permitted run time, or null for an immediate job |
| cancel_requested | boolean | Whether cancellation has been requested |
| context_link | ?string | An Admin console path related to the job, or null |
| payload | ?string | The JSON-encoded job input, or null |
| result | ?string | The JSON-encoded result, or null |
Progress fields stay null until the task reports progress. A task can report progress with no total or no message, which sets progress_total or progress_message to null. The payload can contain identifiers and message content, including in list responses.
Example
Section titled “Example”{ "job_id": "1501314428688998182", "task_type": "bulkUpdateUserFlags", "status": "running", "progress_current": 25, "progress_total": 400, "progress_message": "Updating flags", "error_message": null, "created_at": "2026-08-31T09:00:00.000Z", "started_at": "2026-08-31T09:00:01.000Z", "completed_at": null, "requested_by_user_id": "1478812292088791040", "audit_log_reason": null, "jet_stream_lane": "lifecycle", "jet_stream_seq": "4812", "attempts": 0, "max_attempts": 5, "run_at": null, "cancel_requested": false, "context_link": null, "payload": "{\"user_ids\":[\"1478812292088791040\"]}", "result": null}Job cursor object
Section titled “Job cursor object”Pass all three fields from next_cursor back to List jobs using the corresponding cursor query parameters.
Structure
Section titled “Structure”| Field | Type | Description |
|---|---|---|
| bucket_day | string | The cursor’s UTC date as YYYY-MM-DD |
| created_at | ISO8601 timestamp | The cursor’s creation time |
| job_id | snowflake | The cursor’s job identifier |
Example
Section titled “Example”{ "bucket_day": "2026-08-30", "created_at": "2026-08-30T22:41:07.512Z", "job_id": "1500901337221828608"}Job statuses
Section titled “Job statuses”| Value | Description |
|---|---|
| queued | The job was recorded and no later status has been recorded |
| running | The job was recorded as started |
| succeeded | The job was recorded as completed successfully |
| cancelled | The task read the cancellation request and stopped |
| deadletter | The job was recorded as failed, including a failure to queue it |
queued and running accept cancellation requests. The other statuses are terminal. A cancellation request does not guarantee that the task will stop.
The queue drops a job 7 days after it was queued. A job still recorded as queued or running after 8 days is set to deadletter with the error Expired from the job queue.
Processing lanes
Section titled “Processing lanes”jet_stream_lane identifies the job’s processing group.
| Value | Description |
|---|---|
| realtime | Mention processing |
| unfurl | Link previews |
| lifecycle | Account, guild, moderation, archive and bulk work |
| batch | Scheduled maintenance and index work |
Background job task types
Section titled “Background job task types”Use the returned task_type value to filter List jobs.
The tasks queued by Bulk jobs are bulkUpdateUserFlags, bulkUpdateSuspiciousActivityFlags, bulkUpdateGuildFeatures, bulkAddGuildMembers, and bulkScheduleUserDeletion. harvestUserData and harvestGuildData build archives, sendSystemDm delivers a system DM broadcast, and refreshSearchIndex rebuilds a search index.
List jobs
Section titled “List jobs”GET/v1/admin/jobsReturns a page of Admin job objects, newest first, within the requested lookback window. Requires jobs:view.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| limit? | integer | The maximum number of jobs to return (1-200, default 50) |
| cursor_bucket_day? | string | next_cursor.bucket_day as a YYYY-MM-DD UTC date |
| cursor_created_at? | string | next_cursor.created_at as an ISO 8601 timestamp (1-64 characters) |
| cursor_job_id? | snowflake | The job identifier from next_cursor.job_id |
| max_lookback_days? | integer | The number of days before today to include (1-60, default 14) |
| status? | string | Filter by recorded job status |
| task_type? | string | Filter by task type (1-128 characters) |
| requested_by_user_id? | snowflake | Filter by recorded requester |
Supply all three cursor parameters together or omit all three. An incomplete or malformed cursor returns 400 INVALID_FORM_BODY. An unknown task type returns an empty page. A full page always returns next_cursor, so the next request can return an empty page.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| jobs | array[Admin job object] | The jobs in this page |
| next_cursor | ?job cursor object | The cursor for the next request, or null |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The job page was returned |
| 400 | error response | INVALID_FORM_BODY because a query parameter is invalid |
Side effects
Section titled “Side effects”The operation records no Admin audit entry.
Rate limit
Section titled “Rate limit”600 requests per minute for each authenticated user, on the admin:jobs:view bucket.
List active jobs
Section titled “List active jobs”GET/v1/admin/jobs/activeReturns recorded active jobs as Admin job objects. Requires jobs:view.
This operation has no filters or pagination. The stored status and progress can be behind the work the task has already done.
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| jobs | array[Admin job object] | The recorded active jobs |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The active jobs were returned |
Side effects
Section titled “Side effects”The operation records no Admin audit entry.
Rate limit
Section titled “Rate limit”600 requests per minute for each authenticated user, on the admin:jobs:view bucket.
Get job
Section titled “Get job”GET/v1/admin/jobs/{job_id}Returns one Admin job object. Requires jobs:view.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| job_id | snowflake | The ID of the job |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| job | Admin job object | The job |
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The job was returned |
| 404 | {"error": "job_not_found"} | No job record has this identifier |
A 404 response uses this single-field body rather than the standard error response. A missing or expired record does not mean the work never ran.
Side effects
Section titled “Side effects”The operation records no Admin audit entry.
Rate limit
Section titled “Rate limit”600 requests per minute for each authenticated user, on the admin:jobs:view bucket.
Cancel job
Section titled “Cancel job”PUT/v1/admin/jobs/{job_id}/cancellationRequests cooperative cancellation of a job and reports whether the request was recorded. Requires jobs:cancel.
Path parameters
Section titled “Path parameters”| Field | Type | Description |
|---|---|---|
| job_id | snowflake | The ID of the job |
Response body
Section titled “Response body”| Field | Type | Description |
|---|---|---|
| cancelled | boolean | Whether a cancellation request was recorded |
Returns false for a missing or terminal job. Repeating a request for a queued or running job returns true.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | response body | The request was evaluated, whether or not the flag changed |
Side effects
Section titled “Side effects”Sets cancel_requested to true for a queued or running job. sendSystemDm, syncDisposableEmailDomains, bulkBanFileShas, bulkDeleteMessagesForUsers, and the tasks queued by Bulk jobs check for the request while they run and stop at the next check. Other tasks run to the end. Completed work is not undone. A status of cancelled means the task stopped because of the request.
The operation records one Admin audit entry with action cancel_job, target type bulk_job, target ID equal to job_id, and metadata key cancelled. The entry uses target type bulk_job for every task type, and FiveCord records it when cancelled is false too.
Rate limit
Section titled “Rate limit”600 requests per minute for each authenticated user, on the admin:jobs:view bucket.