Trabalhos (Jobs)

Estas rotas listam os trabalhos (jobs) em segundo plano registrados e solicitam o cancelamento. Crie trabalhos através de Queue bulk job, Create system DM broadcast, Refresh search index ou uma solicitação de archive.

As leituras exigem jobs:view e o cancelamento exige jobs:cancel. Todas as operações nesta página compartilham o bucket admin:jobs:view. As três leituras não registram nenhuma entrada de auditoria Admin audit entry, e o cancelamento registra uma.

Objeto Admin job

Um objeto descreve um trabalho (job) registrado. Estas rotas só podem alterar cancel_requested.

Estrutura

Campo	Tipo	Descrição
job_id	snowflake	O ID do trabalho
task_type	string	O tipo de tarefa do trabalho em segundo plano que o trabalho executa
status	string	O último status do trabalho registrado
progress_current	?integer	As unidades de trabalho relatadas como concluídas, ou null
progress_total	?integer	O total de unidades de trabalho relatado, ou null
progress_message	?string	A última mensagem de progresso relatada, ou null
error_message	?string	O motivo da falha registrado, ou null
created_at	ISO8601 timestamp	A hora em que o trabalho foi registrado
started_at	?ISO8601 timestamp	A última hora de início registrada, ou null quando nenhum início foi registrado
completed_at	?ISO8601 timestamp	A hora registrada de conclusão, cancelamento ou falha, ou null
requested_by_user_id	?snowflake	O solicitante registrado, ou null
audit_log_reason	?string	O motivo do log de auditoria registrado, ou null
jet_stream_lane	?string	A pista de processamento atribuída, ou null
jet_stream_seq	?string	A sequência da fila registrada como uma string decimal, ou null
attempts	integer	A contagem de tentativas registrada, não um total de todas as execuções
max_attempts	integer	O limite de tentativas registrado no momento em que entrou na fila. As tentativas param no limite de entrega da pista, que pode ser diferente deste valor
run_at	?ISO8601 timestamp	O tempo de execução permitido mais cedo, ou null para um trabalho imediato
cancel_requested	boolean	Se o cancelamento foi solicitado
context_link	?string	Um caminho no console de Admin relacionado ao trabalho, ou null
payload	?string	A entrada do trabalho codificada em JSON, ou null
result	?string	O resultado codificado em JSON, ou null

Os campos de progresso permanecem null até que a tarefa relate progresso. Uma tarefa pode relatar progresso sem total ou sem mensagem, o que define progress_total ou progress_message como null. O payload pode conter identificadores e conteúdo de mensagem, inclusive em respostas de lista.

Exemplo

{
  "job_id": "1501314428688998182",
  "task_type": "bulkUpdateUserFlags",
  "status": "running",
  "progress_current": 25,
  "progress_total": 400,
  "progress_message": "Atualizando 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
}

Objeto Job cursor

Passe todos os três campos do next_cursor de volta para List jobs usando os parâmetros de consulta do cursor correspondentes.

Estrutura

Campo	Tipo	Descrição
bucket_day	string	A data UTC do cursor como `YYYY-MM-DD`
created_at	ISO8601 timestamp	O horário de criação do cursor
job_id	snowflake	O identificador do trabalho do cursor

Exemplo

{
  "bucket_day": "2026-08-30",
  "created_at": "2026-08-30T22:41:07.512Z",
  "job_id": "1500901337221828608"
}

Job statuses (Status dos trabalhos)

Valor	Descrição
queued	O trabalho foi registrado e nenhum status posterior foi registrado
running	O trabalho foi registrado como iniciado
succeeded	O trabalho foi registrado como concluído com sucesso
cancelled	A tarefa leu a solicitação de cancelamento e parou
deadletter	O trabalho foi registrado como falho, incluindo uma falha ao colocá-lo na fila

queued e running aceitam solicitações de cancelamento. Os outros status são terminais. Uma solicitação de cancelamento não garante que a tarefa irá parar.

Processing lanes (Pistas de processamento)

jet_stream_lane identifica o grupo de processamento do trabalho.

Valor	Descrição
realtime	Processamento de menções
unfurl	Pré-visualizações de links
lifecycle	Trabalhos em lote, arquivamento, moderação, guilda e conta
batch	Manutenção programada e trabalho de indexação

Background job task types (Tipos de tarefa de trabalho em segundo plano)

Use o valor task_type retornado para filtrar List jobs.

As tarefas colocadas na fila por Bulk jobs são bulkUpdateUserFlags, bulkUpdateSuspiciousActivityFlags, bulkUpdateGuildFeatures, bulkAddGuildMembers, e bulkScheduleUserDeletion. harvestUserData e harvestGuildData criam archives, sendSystemDm entrega um system DM broadcast, e refreshSearchIndex reconstrói um search index.

List jobs

GET/v1/admin/jobs

Retorna uma página de objetos Admin job, com os mais recentes primeiro, dentro da janela de lookback solicitada. Requer jobs:view.

Parâmetros de consulta

Campo	Tipo	Descrição
limit?	integer	O número máximo de trabalhos a retornar (1-200, padrão 50)
cursor_bucket_day?	string	`next_cursor.bucket_day` como uma data UTC `YYYY-MM-DD`
cursor_created_at?	string	`next_cursor.created_at` como um timestamp ISO 8601 (1-64 caracteres)
cursor_job_id?	snowflake	O identificador do trabalho em `next_cursor.job_id`
max_lookback_days?	integer	O número de dias antes da data do cursor ou de hoje a incluir (1-60, padrão 14)
status?	string	Filtrar por job status registrado
task_type?	string	Filtrar por task type (1-128 caracteres)
requested_by_user_id?	snowflake	Filtrar por solicitante registrado

Forneça todos os três parâmetros do cursor juntos ou omita os três. Um cursor incompleto ou malformado retorna 400 INVALID_FORM_BODY. Um tipo de tarefa desconhecido retorna uma página vazia.

Corpo da resposta

Campo	Tipo	Descrição
jobs	array[Objeto Admin job]	Os trabalhos nesta página
next_cursor	?Objeto job cursor	O cursor para a próxima solicitação, ou null

Resposta

Status	Corpo	Condição
200	corpo da resposta	A página de trabalho foi retornada
400	error response	`INVALID_FORM_BODY` porque um parâmetro de consulta é inválido

Efeitos colaterais

A operação não registra nenhuma Admin audit entry.

Limite de taxa

600 solicitações por minuto para cada usuário autenticado, no bucket admin:jobs:view.

List active jobs

GET/v1/admin/jobs/active

Retorna os trabalhos ativos registrados como objetos Admin job. Requer jobs:view.

Esta operação não possui filtros ou paginação. O status e o progresso armazenados podem estar atrasados em relação ao trabalho que a tarefa já concluiu.

Corpo da resposta

Campo	Tipo	Descrição
jobs	array[Objeto Admin job]	Os trabalhos ativos registrados

Resposta

Status	Corpo	Condição
200	corpo da resposta	Os trabalhos ativos foram retornados

Efeitos colaterais

A operação não registra nenhuma Admin audit entry.

Limite de taxa

600 solicitações por minuto para cada usuário autenticado, no bucket admin:jobs:view.

Get job

GET/v1/admin/jobs/{job_id}

Retorna um objeto Admin job. Requer jobs:view.

Parâmetros de caminho

Campo	Tipo	Descrição
job_id	snowflake	O ID do trabalho

Corpo da resposta

Campo	Tipo	Descrição
job	Objeto Admin job	O trabalho

Resposta

Status	Corpo	Condição
200	corpo da resposta	O trabalho foi retornado
404	`{"error": "job_not_found"}`	Nenhum registro de trabalho possui esse identificador

Uma resposta 404 usa este corpo de campo único em vez da resposta de erro padrão. Um registro ausente ou expirado não significa que o trabalho nunca foi executado.

Efeitos colaterais

A operação não registra nenhuma Admin audit entry.

Limite de taxa

600 solicitações por minuto para cada usuário autenticado, no bucket admin:jobs:view.

Cancel job

PUT/v1/admin/jobs/{job_id}/cancellation

Audit reason

Solicita o cancelamento cooperativo de um trabalho e relata se a solicitação foi registrada. Requer jobs:cancel.

Parâmetros de caminho

Campo	Tipo	Descrição
job_id	snowflake	O ID do trabalho

Corpo da resposta

Campo	Tipo	Descrição
cancelled	boolean	Se uma solicitação de cancelamento foi registrada

Retorna false para um trabalho ausente ou terminal. A repetição de uma solicitação para um trabalho na fila ou em execução retorna true.

Resposta

Status	Corpo	Condição
200	corpo da resposta	A solicitação foi avaliada, tendo o sinalizador mudado ou não

Efeitos colaterais

Define cancel_requested como true para um trabalho na fila ou em execução. sendSystemDm, syncDisposableEmailDomains, bulkBanFileShas, bulkDeleteMessagesForUsers, e as tarefas enfileiradas por Bulk jobs verificam a solicitação enquanto são executadas e param na próxima verificação. Outras tarefas são executadas até o fim. O trabalho concluído não é desfeito. Um status de cancelled significa que a tarefa parou devido à solicitação.

A operação registra uma Admin audit entry com ação cancel_job, tipo alvo bulk_job, ID de alvo igual a job_id e a chave de metadados cancelled. A entrada usa o tipo alvo bulk_job para cada tipo de tarefa, e o Decoding Chat a registra mesmo quando cancelled é falso.

Limite de taxa

600 solicitações por minuto para cada usuário autenticado, no bucket admin:jobs:view.