---
title: "Retrieve a job"
method: GET
path: "/jobs/{id}"
tags: ["Jobs"]
---

# Retrieve a job

`GET /jobs/{id}`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/jobs/{id}`
- Auth: HTTP bearer

Retrieve a background job by `id` to follow its progress. An operation that touches more contacts than fits in one request (for example [Delete a custom contact field](#delete-contact-fields-id) or [Rename a custom field's key](#post-contact-fields-id-rename) above 5,000 holders, or a campaign validation over more than 5,000 recipients) answers `202` with a job. Poll this until `status` is `COMPLETED`, `FAILED` or `CANCELED`; `processed` of `total` is the progress. A failed job keeps the work it finished; retry it from the dashboard (Settings → Jobs). Reading a job takes the read capability of the resource it changes (`contacts:read` for a custom-field job, `campaigns:read` for a campaign check). Requires the `contacts:read` capability.

## Response `200`

The job.

- Job
  - `object` 'job', required
  - `id` string, required
  - `kind` string, required
  - `status` 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELED', required
  - `total` integer, nullable, required
  - `processed` integer, required
  - `failed` integer, required
  - `error` string, nullable, required
  - `created_at` string, required
  - `completed_at` string, nullable, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the read capability of the resource this job changes.
- `404`: Job not found.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)