# Show progress of a job

> How far a job is that another route started, by its job_token.

- Effect: Read - Changes nothing.
- Idempotent: yes
- Stability: stable
- MCP tool: `manitu_job_get` on https://mcp.manitu.de/mcp
- REST: `POST https://api.manitu.de/v1/job/get`
- Page: /reference/job/get/

## MCP tool

`manitu_job_get`

### Description for the model

Shows the status of a background job (how far it is) that a manitu tool started in the manitu customer account this connection works in - a restart or snapshot of a virtual server, a database copy and the like - by the job_token that tool answered, passed as it is. status pending or running: not finished yet - wait and ask again, not more often than about once a minute; some take many minutes. succeeded: finished. failed: it failed - tell the user, do not simply start it again (result.error_list may say why). result has what it left for the user once finished - an installed application's administrator and where to log in, the versions of an update. Refused (forbidden) when this access may not see the package or server the job works on. The token is a secret of this job: never show it.

Reasons it may answer: resource_not_found, permission_missing, primary_access_required, job_token_malformed.

### Arguments

- `job_token` (string, required, write-only) - The job_token the starting tool answered - passed as it is, never built. (minLength `1`; maxLength `255`)

### Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "manitu_job_get",
    "arguments": {
      "job_token": "eyJwYWdlIjoyfQ"
    }
  }
}
```

## REST

`POST https://api.manitu.de/v1/job/get`

### Description

Returns the status of a background job of the account - a restart or snapshot of a virtual server, a database copy and the like - by the job_token the route that started it answered (job_token_malformed if it is not one). status pending or running: not finished yet; succeeded: finished; failed: it failed, result.error_list may say why. result holds what the job left once finished - an installed application's administrator and where to log in, the versions of an update. Refused when the access may not see the package or server the job works on (permission_missing, primary_access_required), and when there is no such job (resource_not_found). Changes nothing.

### Authentication

One of `X-API-Key`, `Authorization: Bearer …` - never more than one in a request.

### Request body

JSON; unknown fields are refused.

- `job_token` (string, required, write-only) - The job_token the starting tool answered - passed as it is, never built. (minLength `1`; maxLength `255`)

### Response

In `data`; the rest of the body as on every call.

- `kind` (string | null, required) - What is being done, a lower_snake_case code of the backend, e.g. power_reboot - its values are the backend's own, an open set. null where the backend does not name it. (one of `"vserver_create"`, `"vserver_delete"`, `"power_start"`, `"power_stop"`, `"power_reboot"`, `"reinstall"`, `"ptr_set"`, `"vnc_enable"`, `"vnc_disable"`, `"rescue_system_enable"`, `"rescue_system_disable"`, `"snapshot_create"`, `"snapshot_delete"`, `"snapshot_delete_all"`, `"snapshot_revert"`, `"setup_finish"`, `"iso_eject"`, `"contract_termination"`, `"application_install"`, `"application_update"`, `"permission_set"`, `"database_copy"`, `"network_discovery"`, `null`; pattern `"^[a-z0-9]+(_[a-z0-9]+)*$"`)
- `job_id` (string | null) - The id of this run, where the backend keeps one; null otherwise.
- `status` (any, required) - pending: waiting to start; running: started, not finished; succeeded: finished, everything went through; failed: finished, but it or part of it failed. cancelled is reserved and not sent. (one of `"pending"`, `"running"`, `"succeeded"`, `"failed"`)
- `created_at` (string | null, required) - When it was asked for. (format `date-time`)
- `started_at` (string | null) - When it started; null while pending, and where the backend does not record it. (format `date-time`)
- `ended_at` (string | null) - When it finished; null until then. (format `date-time`)
- `updated_at` (string | null) - When it last changed. (format `date-time`)
- `job_token` (string | null, required) - What the operation that follows a job takes to find this one - passed as it is, never built or changed. A secret of this job: not to be shown to anyone. null where there is none. (minLength `1`)
- `result` (object | null, required) - What it left for the user, when it is finished - null for a job that keeps none.
  - `result.admin` (object | null, required) - The administrator of an application manitu installed.
    - `result.admin.username` (string, required)
    - `result.admin.password` (string | null, required) - A secret; null where it is withheld (secrets_withheld).
    - `result.admin.mail_address` (string, required)
  - `result.administration_url` (string | null, required) - Where an installed application is administered.
  - `result.version` (object | null, required) - The versions of an application update.
    - `result.version.old` (string | null, required)
    - `result.version.new` (string | null, required)
  - `result.dump` (object | null, required) - The dump files a database copy wrote, relative to the package.
    - `result.dump.source` (string | null, required)
    - `result.dump.target` (string | null, required)
  - `result.error_list` (array of string, required) - Why it failed, as codes - e.g. quota_exceeded, extra_files_found, nextcloud_too_old.
- `secrets_withheld` (boolean, required) - A secret in result is left out here (an answer to an agent).

### Statuses

- `200` Success.
- `400` The input is wrong, or the request itself (INVALID_INPUT). Each entry names its field and its reason - correct the input and call again.
- `401` No credential was presented, or it was not recognised (UNAUTHENTICATED).
- `403` The credential is valid, but may not do this (PERMISSION_DENIED). The reason says why - another credential is the way, not a repeat.
- `404` What the call names does not exist, or not for this caller (NOT_FOUND). Look it up again - do not guess another.
- `429` Too many calls. The Retry-After header says when to try again.
- `500` The server failed. Nothing about the request was wrong. Whether a change took effect is not known - check before trying it again.
- `503` The channel this operation forwards through is unavailable.

### Example

```sh
curl -X POST \
  'https://api.manitu.de/v1/job/get' \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"job_token":"eyJwYWdlIjoyfQ"}'
```

## Example result

```json
{
  "kind": "vserver_create",
  "job_id": "string",
  "status": "pending",
  "created_at": "2026-10-23T12:00:00+02:00",
  "started_at": "2026-10-23T12:00:00+02:00",
  "ended_at": "2026-10-23T12:00:00+02:00",
  "updated_at": "2026-10-23T12:00:00+02:00",
  "job_token": "eyJwYWdlIjoyfQ",
  "result": {
    "admin": {
      "username": "string",
      "password": "correct-horse-battery",
      "mail_address": "info@example.com"
    },
    "administration_url": "https://www.example.com/",
    "version": {
      "old": "string",
      "new": "string"
    },
    "dump": {
      "source": "string",
      "target": "string"
    },
    "error_list": [
      "string"
    ]
  },
  "secrets_withheld": true
}
```

## Errors

Reasons it is known to fail with - any other may come too; act on the class.

- [`resource_not_found`](/errors/resource_not_found.md) (`NOT_FOUND`) - What the call names does not exist in the account, or not for this access.
- [`permission_missing`](/errors/permission_missing.md) (`PERMISSION_DENIED`) - This access lacks a permission the call needs; the main access of the account can grant it.
- [`primary_access_required`](/errors/primary_access_required.md) (`PERMISSION_DENIED`) - Only the main access of the account may see this job.
- [`job_token_malformed`](/errors/job_token_malformed.md) (`INVALID_INPUT`) - The job_token is none - pass it as the starting tool answered it.
