---
title: "Jobs API Reference | Linkbreakers"
description: "Follow a bulk link creation that runs in the background. Start it with POST /v1/links/bulk/jobs, then check it here until it is done."
canonical: "https://linkbreakers.com/help/api/jobs"
---

# Jobs

Follow a bulk link creation that runs in the background. Start it with `POST /v1/links/bulk/jobs`, then check it here until it is done.

2 entries on this page

## The job object

A bulk link creation running in the background.

You get one back from `POST /v1/links/bulk/jobs`, and read it again with `GET /v1/jobs/{id}` until it is finished. Its status says where it stands:

* pending: accepted, waiting to run.
* running: creating the links now.
* succeeded: done; `linksBulkCreate.linkIds` holds the created link IDs.
* failed: `error` says why. No link was created: a batch is all or nothing.

A job can be read for 24 hours after it finishes.

`completedAt` string (date-time)

When the job finished, once it has.

`createdAt` string (date-time)

When the job was accepted.

`error` object

Set when status is JOB\_STATUS\_FAILED.

2 child attributes

`codeType` string

Stable error code, the same codeType a synchronous call would return.

`message` string

Human-readable explanation.

`id` string

Job ID (UUID).

`itemCount` integer (int32)

How many items the job was submitted with.

`linksBulkCreate` object

Set when a JOB\_TYPE\_LINKS\_BULK\_CREATE job succeeded.

1 child attribute

`linkIds` array of string

IDs of the created links, in the order they were submitted. Fetch each with GET /v1/links/{id}.

`status` enum

Where the job stands. Poll until JOB\_STATUS\_SUCCEEDED or JOB\_STATUS\_FAILED.

Allowed values

* `JOB_STATUS_PENDING` Accepted and waiting to run.
* `JOB_STATUS_RUNNING` Running now.
* `JOB_STATUS_SUCCEEDED` Finished; the result is set.
* `JOB_STATUS_FAILED` Finished without doing its work; error says why. Nothing was created.

`statusUrl` string

Path to poll for this job's status.

`type` enum

What the job does.

Allowed values

* `JOB_TYPE_LINKS_BULK_CREATE` Creates a batch of links (POST /v1/links/bulk/jobs).

Example job

```json
{
  "completedAt": "2026-03-14T09:30:12Z",
  "createdAt": "2026-03-14T09:30:00Z",
  "error": {
    "codeType": "INSUFFICIENT_PLATFORM_CREDITS",
    "message": "Not enough platform credits to create 24 links: 12 credits left."
  },
  "id": "1f8e3c6a-7d2b-4a9e-b5c1-8e4f0a6d2c79",
  "itemCount": 24,
  "linksBulkCreate": {
    "linkIds": [
      "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
      "6e2b7f40-3c1a-4d8e-9b25-7a0f1c3d5e82"
    ]
  },
  "status": "JOB_STATUS_SUCCEEDED",
  "statusUrl": "/v1/jobs/1f8e3c6a-7d2b-4a9e-b5c1-8e4f0a6d2c79",
  "type": "JOB_TYPE_LINKS_BULK_CREATE"
}
```

### Parameters

`id` string 

path

Required

The job ID returned when the job was accepted.

### Response

200

Returns [the job object](#jobs-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/jobs/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

Source: https://linkbreakers.com/help/api/jobs
