---
title: "Read a job"
method: GET
path: "/products/help-desk/jobs/{job_id}"
tags: ["help-desk"]
---

# Read a job

`GET /products/help-desk/jobs/{job_id}`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/products/help-desk/jobs/{job_id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/products/help-desk/jobs/:job_id/get.ts> (a function with typed inputs; its response is checked against the schema)

A job's state, progress and, once done, what it did; poll it until `state` is done or failed. It is read as it stands from the moment its start answers. A job that nothing has moved for 30 minutes is ended as it is read, failed with the reason `stopped`. Org admins only, from their own session: an export's result is a link to everything the desk holds of a person.

## Path parameters

- `job_id` string, required

## Response `200`

The job.

- object
  - `data` HelpDeskJob, required: An asynchronous job. It runs until `state` is done or failed, and is deleted 7 days after, an export's files with it. A queued or running job that nothing has moved for 30 minutes is ended failed, `stopped`, when it is next read.
    - `job_id` string, required
    - `kind` 'export_requester' | 'erase_requester' | 'apply_rules' | 'kb_publish', required
    - `state` 'queued' | 'running' | 'done' | 'failed', required
    - `params` object, required: What the job acts on: `requester_id` for a requester's export or erasure; nothing for the routing re-apply.
      - `requester_id` string
    - `progress` object, required
      - `done` integer, required: Tickets done so far: exported, erased, or checked against the rules.
      - `total` integer, nullable: About how many there are to do, when known.
    - `result` union: What a done job did.
      - object: An export: newline-delimited JSON (one object a line) in files sealed in the desk's vault, with the requester's own fields, each of their requests and the public timeline of each, as the requester reads it. `download_url` is a single-use link, good for 24 hours, to the last file, whose last line lists every earlier file with a link of its own. Each attachment carries a single-use link of its own.
        - `ingot_id` string, required
        - `download_url` string, required
        - `expires_at` integer, required
        - `parts` integer, required: The files the export is.
        - `size_bytes` integer, required
        - `tickets` integer, required
        - `events` integer, required
        - `attachments` integer, required
        - `unlinked_attachments` integer, required: Attachments listed without a link: deleted after the export read their page. A file deleted before is on no timeline, so the export does not list it.
      - object: An erasure.
        - `tickets` integer, required
        - `events` integer, required
        - `ingots` integer, required: Message, attachment and email files deleted.
        - `export_parts` integer, required: Files of earlier exports of the requester deleted.
      - object: A routing re-apply.
        - `checked` integer, required
        - `routed` integer, required: Tickets a rule changed.
    - `error` string: Why a failed job stopped, in words for the admin.
    - `failure` object: Why a failed job stopped, for the console to act on.
      - `reason` 'legal_hold' | 'desk_inactive' | 'storage_full' | 'bandwidth_exhausted' | 'no_active_plan' | 'requester_gone' | 'requester_erased' | 'not_started' | 'stopped', required
      - `ticket_ids` string[]: For `legal_hold`: the requester's tickets under legal hold (at most 100).
    - `created_at` integer, required
    - `updated_at` integer, required
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `401`: AUTHENTICATION_ERROR — missing or invalid credentials.
- `403`: FORBIDDEN — the caller is not an org admin, or the credential is an API key or an impersonated session. FORBIDDEN — the admin has been removed from the organization since the session began.
- `404`: NOT_FOUND — the desk holds no such job.

## Changes

- **2026-10-28** `a9a10e328ba5`: 12 info
  - the response property `error/details` became required for the status `401`
  - the response property `error/details` became required for the status `403`
  - the response property `error/details` became required for the status `404`
  - the response property `meta` became required for the status `401`
  - …8 more
- **2026-10-28** `56d7c265a77a`: 3 breaking
  - the response property `error/details` became nullable for the status `401`
  - the response property `error/details` became nullable for the status `403`
  - the response property `error/details` became nullable for the status `404`
- **2026-10-27** `ac44ec1f8cfa`: 1 warning
  - added the new `kb_publish` enum value to the `data/kind` response property for the response status `200`
- **2026-10-23** `ad4c62db5e08`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/products/help-desk/jobs/:job_id/get.md)

---

[API](https://skmtc.dev/sparkvault/apis/sparkvault-api.md) - [All operations](https://skmtc.dev/sparkvault/apis/sparkvault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sparkvault/apis/sparkvault-api/revisions/97cfadccd0c0?raw)