---
title: "Poll work that outlived the request that started it"
method: GET
path: "/api/jobs/{job_id}"
tags: ["Jobs"]
---

# Poll work that outlived the request that started it

`GET /api/jobs/{job_id}`

## Request

- Base URL: `https://youspot.com`
- URL: `https://youspot.com/api/jobs/{job_id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://youspot.com/oauth/authorize`, token URL `https://youspot.com/oauth/token`, scopes: `linkedin`)

A tool that cannot finish inside one call enqueues instead, and answers with `task_id`. That id is this `job_id`.

Poll until `terminal` is true. A job that is still going carries `Retry-After`, which is the interval to use. `result` is filled once `state` is `succeeded`, `error` once it is `failed`.

A job is readable only by the member it belongs to.

## Path parameters

- `job_id` integer, required

## Response `200`

The job as it stands.

- Job
  - `success` boolean, required
  - `job_id` integer, required
  - `kind` string, required: What the job does, e.g. `file_import`.
  - `state` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
  - `terminal` boolean, required: True once the state can no longer change. Stop polling.
  - `attempts` integer: Runs so far, including the current one.
  - `progress` object, nullable: Whatever the job checkpoints as it goes. Shape depends on `kind`.
  - `created_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `finished_at` string, date-time, nullable
  - `result` object, nullable: Filled once `state` is `succeeded`.
  - `error` string, nullable: Filled once `state` is `failed`.

## Other responses

- `401`: The request was refused. `error` is stable; read `error_description` for the reason.
- `404`: The request was refused. `error` is stable; read `error_description` for the reason.

---

[API](https://skmtc.dev/youspot/apis/youspot-http-api.md) · [All operations](https://skmtc.dev/youspot/apis/youspot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/youspot/apis/youspot-http-api/revisions/6615ad5d017d?raw)