## Purge and prefetch (`cache-jobs`)

Purge cached URLs or directories, and prefetch given URLs.

Authentication: User (some parameters admin only) · Docs: https://www-sa2.kuxitong.com/en/docs/api/cache-jobs

### GET `/api/v2/cache-jobs`

List purge/prefetch jobs · Authentication: User (some parameters admin only)

Query parameters:

| Field | Type | Required | Description |
|---|---|---|---|
| `page` | integer |  | Page number, starting from 1 Default: 1 |
| `page_size` | integer |  | Items per page Default: 20 |
| `sort` | string |  | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
| `tenant_id` | integer |  | Admin only: filter by tenant (a malformed value returns 422). Ignored for tenant credentials, which only see their own tenant's data |
| `type` | string |  | Only list jobs of this type. Values: ["purge_url","purge_dir","prefetch"] |
| `url` | string |  | If it starts with http:// or https://, exact match on the full URL, normalized as on submission (the job's URL list contains it); otherwise exact match on the host name. |

```sh
curl "https://panel.example.com/api/v2/cache-jobs" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

### POST `/api/v2/cache-jobs`

Create purge/prefetch job · Authentication: User (some parameters admin only)

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string | Yes | purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch. Values: ["purge_url","purge_dir","prefetch"] |
| `urls` | string[] | Yes | http(s)://host/path (normalized, see create); at most 100 entries per prefetch. |

```sh
curl -X POST "https://panel.example.com/api/v2/cache-jobs" \
  -H "X-API-Key: $GOCDN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"purge_url","urls":["https://www.example.com/index.html"]}'
```

### GET `/api/v2/cache-jobs/{id}`

Get purge/prefetch job · Authentication: User (some parameters admin only)

```sh
curl "https://panel.example.com/api/v2/cache-jobs/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"
```

Purge and prefetch object:

| Field | Type | Required | Description |
|---|---|---|---|
| `batches` | integer |  | How many push tasks this submission was split into (prefetch is split by node timeout; purge is always 1). id, urls, status, progress, regions and results are the merged values of all batches of the submission. (read-only) |
| `by_admin` | boolean |  | Whether an administrator submitted the job on the tenant's behalf (true means it does not count toward the tenant's daily quota); false when the tenant submitted it. (read-only) |
| `created_at` | string |  | Created at (read-only) |
| `id` | integer |  | Record ID (read-only) |
| `progress` | CacheJobProgress |  | Progress of the job across all nodes (read-only, counts only). total = nodes that have reported + in-use nodes that have not yet reported (while the job is running); once the job ends only nodes that reported are counted. (read-only) |
| `regions` | CacheJobRegion[] |  | Node progress summarized by region (returned in details only), in descending order of total; nodes without a region are grouped as "Unassigned". Same shape for tenants and administrators; counts only, never node names, IPs or node IDs. (read-only) |
| `results` | CacheJobNodeResult[] |  | Execution result of each node (returned in details only; only administrators see nodes, for tenants this is always an empty array, use progress and regions instead). (read-only) |
| `site_id` | integer |  | Site ID (read-only) |
| `status` | string |  | Status of the push task (if some nodes fail it stays pending and retries with backoff, then becomes failed when retries run out). With several batches, any failed batch makes it failed; otherwise it is running/pending until every batch is done. Values: ["pending","running","done","failed"] (read-only) |
| `tenant_id` | integer |  | Owner tenant (user) ID (read-only) |
| `tenant_name` | string |  | Display name of the tenant that owns the job; tenants calling it see their own name; omitted when the tenant has been deleted. (read-only) |
| `type` | string |  | purge_url = purge URLs; purge_dir = purge directories (URL ends with /); prefetch = prefetch. Values: ["purge_url","purge_dir","prefetch"] |
| `updated_at` | string |  | Updated at (read-only) |
| `urls` | string[] |  | http(s)://host/path (normalized, see create); at most 100 entries per prefetch. |
