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

# Link Jobs

Follow links being created in the background. Start a bulk creation with `POST /v1/links/bulk/jobs`, then read the job here until it is done.

2 entries on this page

## The link job object

Links being created in the background.

You get one back from `POST /v1/links/bulk/jobs`, and read it again with `GET /v1/links/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 link 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 LINK\_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

Link job ID (UUID).

`itemCount` integer (int32)

How many links the job was submitted with.

`linksBulkCreate` object

Set when a LINK\_JOB\_TYPE\_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 LINK\_JOB\_STATUS\_SUCCEEDED or LINK\_JOB\_STATUS\_FAILED.

Allowed values

* `LINK_JOB_STATUS_PENDING` Accepted and waiting to run.
* `LINK_JOB_STATUS_RUNNING` Running now.
* `LINK_JOB_STATUS_SUCCEEDED` Finished; the result is set.
* `LINK_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

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

Example link 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": "LINK_JOB_STATUS_SUCCEEDED",
  "statusUrl": "/v1/links/jobs/1f8e3c6a-7d2b-4a9e-b5c1-8e4f0a6d2c79",
  "type": "LINK_JOB_TYPE_BULK_CREATE"
}
```

### Parameters

`id` string 

path

Required

The link job ID returned when the job was accepted.

### Response

200

Returns [the link job object](#link-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/links/jobs/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

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