# Cancel a job

> `202` with the job's `lifecycle` now — the request to stop was accepted; the job read says how it ended.

`PUT https://api.refabric.com/v1/jobs/{job_id}/cancel`

**Authentication.** A key with `jobs:cancel`: cancelling changes a running job.

**Common use cases**

- Stop a job you no longer need.

**Conflicts.** A job that already ended answers `202` and nothing changes.

**See also**

- `GET /v1/jobs/{job_id}`

Authentication: `Authorization: Key $REFABRIC_API_KEY`, scope `jobs:cancel`.

## Path parameters

- `job_id` (string, _required_)

## Header parameters

- `Refabric-Version` (string, _optional_, format: date) — The contract version you wrote against (a date). Absent: the current version.
- `X-Request-ID` (string, _optional_, max length 128) — Your own id for this request; we answer it back under X-Client-Request-ID.

## Response 202

Accepted: the work goes on after this answer; the body says where to follow it.

- `job_id` (string, _required_) — The job you asked to stop.
  Example: `9b2f4c1d0e8a`
- `lifecycle` (string, _required_) — Where the job is now: `queued` or `running` — the job is asked to stop; `terminal` — the job had already ended and is left as it is. Read `GET /v1/jobs/{job_id}` for how it ended (`outcome`).
  Values: `queued` (Accepted and waiting to start.); `running` (Being made.); `terminal` (Ended. `outcome` says how.)
  Example: `running`

```json
{
  "job_id": "9b2f4c1d0e8a",
  "lifecycle": "running"
}
```

## Response 401

No valid API key was sent.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 403

Your key or your plan does not allow this.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 404

Nothing has this address.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 429

Too many requests: wait for the number of seconds in the Retry-After header.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Response 500

Something went wrong on our side; retry, and quote the request id if it keeps happening.

```json
{
  "error": {
    "code": "string",
    "type": "invalid_request",
    "message": "string",
    "field": "string",
    "retryable": true,
    "docs": "string",
    "request_id": "string",
    "ctx": {
      "required": 0,
      "balance": 0,
      "retry_after": 0
    },
    "input": null,
    "job_id": "string",
    "required": 0,
    "balance": 0
  }
}
```

## Request

```python
import os
import requests

url = "https://api.refabric.com/v1/jobs/{job_id}/cancel"

headers = {"Authorization": f"Key {os.environ['REFABRIC_API_KEY']}"}

response = requests.put(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.refabric.com/v1/jobs/{job_id}/cancel';
const options = {method: 'PUT', headers: {Authorization: `Key ${process.env.REFABRIC_API_KEY}`}};

try {
    const response = await fetch(url, options);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}
```

```bash
curl --request PUT \
    --url https://api.refabric.com/v1/jobs/{job_id}/cancel \
    --header "Authorization: Key $REFABRIC_API_KEY"
```