Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
9.4 KB
Raw Blame
---
# SPDX-License-Identifier: AGPL-3.0-or-later
title: Jobs
description: List background jobs, follow their progress and request cancellation.
---

import RouteHeader from '@/components/RouteHeader.astro';

Admin requests such as [Queue bulk job](/admin-api/bulk-jobs/#queue-bulk-job), [Bulk add blocklist entries](/admin-api/blocklists/#bulk-add-blocklist-entries), [Create system DM broadcast](/admin-api/system-dms/#create-system-dm-broadcast), [Refresh search index](/admin-api/search-indexes/#refresh-search-index) and [archive](/admin-api/archives/) requests return a job ID that you follow here. Fluxer deletes a job record about 90 days after the job was queued.

## Admin job object

### Structure

| Field | Type | Description |
| --- | --- | --- |
| job_id | snowflake | The ID of the job |
| task_type | string | The [task type](#background-job-task-types) the job runs |
| status | string | The latest recorded [job status](#job-statuses) |
| progress_current | ?integer | The units of work completed |
| progress_total | ?integer | The total units of work |
| progress_message | ?string | The latest progress message |
| error_message | ?string | The failure reason |
| created_at | ISO8601 timestamp | The time the job was recorded |
| started_at | ?ISO8601 timestamp | The latest recorded start time |
| completed_at | ?ISO8601 timestamp | The completion, cancellation or failure time |
| requested_by_user_id | ?snowflake | The user who requested the job |
| audit_log_reason | ?string | The audit log reason |
| jet_stream_lane | ?string | The [processing lane](#processing-lanes) |
| jet_stream_seq | ?string | The queue sequence as a decimal string |
| attempts | integer | The number of attempts so far |
| max_attempts | integer | The attempt limit recorded at queue time. Retries stop at the lane's delivery limit, which can differ |
| run_at | ?ISO8601 timestamp | The earliest 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 |
| payload | ?string | The JSON-encoded job input |
| result | ?string | The JSON-encoded result |

`payload` can include user IDs and message text. Status and progress can lag a few moments behind the running task. Use the [archive routes](/admin-api/archives/) to track archive progress and failures.

### Example

```json
{
  "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

To get the next page, pass all three `next_cursor` fields to [List jobs](#list-jobs) as the matching `cursor_*` query parameters.

### 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 ID |

## Job statuses

| Value | Description |
| --- | --- |
| queued | The job was recorded and has not started |
| running | The job started |
| succeeded | The job completed |
| cancelled | The task stopped after a cancellation request |
| deadletter | The job failed, including a failure to queue it |

A job still `queued` or `running` after 8 days becomes `deadletter` with the error `Expired from the job queue`.

## Processing lanes

List jobs never returns `realtime` or `unfurl` work, because those tasks have no job record.

| Value | Description |
| --- | --- |
| realtime | Mention processing |
| unfurl | Link previews |
| lifecycle | Account, guild, moderation, archive and bulk work |
| batch | Scheduled maintenance, index work and thread maintenance |
| crosspost | [Announcement channel](/topics/announcement-channels/) delivery, copy updates and follower cleanup |

## Background job task types

The table lists the task types that admin requests queue and the guild and thread work you are most likely to see. Other task types can also appear.

| Value | Description |
| --- | --- |
| bulkUpdateUserFlags | A [bulk job](/admin-api/bulk-jobs/) |
| bulkUpdateGuildFeatures | A [bulk job](/admin-api/bulk-jobs/) |
| bulkAddGuildMembers | A [bulk job](/admin-api/bulk-jobs/) |
| bulkScheduleUserDeletion | A [bulk job](/admin-api/bulk-jobs/) |
| bulkBanFileShas | Adds entries from [Bulk add blocklist entries](/admin-api/blocklists/#bulk-add-blocklist-entries) |
| harvestUserData | Builds a user [archive](/admin-api/archives/) |
| harvestGuildData | Builds a guild [archive](/admin-api/archives/) |
| sendSystemDm | Delivers a [system DM broadcast](/admin-api/system-dms/) |
| refreshSearchIndex | Rebuilds a [search index](/admin-api/search-indexes/) |
| guildProcessDeletion | Removes the records of a deleted guild |
| removeChannelFollowers | Removes the follower webhooks of a deleted or converted announcement channel |
| deleteChannelThreads | Deletes the threads of a deleted parent channel |
| syncThreadSearchDocument | Updates the thread search index |
| backfillThreadSearch | Backfills the thread search index |
| repairThreadIndexes | Rebuilds thread list entries |
| seedThreadPermissions | Adds thread permissions to a guild's channel overwrites and @everyone role where Send Messages is set |

`bulkDeleteMessagesForUsers` runs a [bulk job](/admin-api/bulk-jobs/) that deletes users' messages, and `removeThreadMembershipsForGuildMember` removes the thread memberships of a user who is no longer a guild member.

## List jobs

<RouteHeader method="GET" path="/v1/admin/jobs" />

Returns [Admin job](#admin-job-object) objects, newest first. You need `jobs:view`.

### 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 ID 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 [job status](#job-statuses) |
| task_type? | string | Filter by [task type](#background-job-task-types) (1-128 characters) |
| requested_by_user_id? | snowflake | Filter by requester |

`next_cursor` is set whenever a page is full, and the next page can be empty. It is null when there are no more jobs in the lookback window.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| jobs | array[[Admin job](#admin-job-object) object] | The jobs in this page |
| next_cursor | ?[job cursor](#job-cursor-object) object | The cursor for the next request |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The job page was returned |
| 400 | [error response](/admin-api/#error-response) | `INVALID_FORM_BODY` because a query parameter is invalid |

The rate limit is 600 requests per minute, on the `admin:jobs:view` bucket.

## List active jobs

<RouteHeader method="GET" path="/v1/admin/jobs/active" />

Returns the [Admin job](#admin-job-object) objects of queued and running jobs, with no filters or pagination. You need `jobs:view`.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| jobs | array[[Admin job](#admin-job-object) object] | The recorded active jobs |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The active jobs were returned |

The rate limit is 600 requests per minute, on the `admin:jobs:view` bucket.

## Get job

<RouteHeader method="GET" path="/v1/admin/jobs/{job_id}" />

Returns one [Admin job](#admin-job-object) object. You need `jobs:view`.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| job | [Admin job](#admin-job-object) object | The job |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | The job was returned |
| 404 | `{"error": "job_not_found"}` | No job record has this ID |

The rate limit is 600 requests per minute, on the `admin:jobs:view` bucket.

## Cancel job

<RouteHeader method="PUT" path="/v1/admin/jobs/{job_id}/cancellation" auditReason />

Requests cancellation of a queued or running job. You need `jobs:cancel`.

### Response body

| Field | Type | Description |
| --- | --- | --- |
| cancelled | boolean | Whether a cancellation request was recorded |

### Response

| Status | Body | Condition |
| --- | --- | --- |
| 200 | response body | `cancelled` is false when the job doesn't exist or has finished |

Only `sendSystemDm`, `bulkBanFileShas` and the [bulk job](/admin-api/bulk-jobs/) tasks check for the request. They stop at their next check, set the status to `cancelled` and keep the work already done. Other tasks run to the end.

Every request records an [Admin audit entry](/admin-api/#admin-audit-entry-object) with action `cancel_job`, target type `bulk_job`, target ID `job_id` and metadata key `cancelled`, even when `cancelled` is false.

The rate limit is 600 requests per minute, on the `admin:jobs:view` bucket.