# Managing Jobs

Use this guide to interpret batch statuses, review quotes, start or stop processing, update or delete jobs, and paginate job listings.

## Job lifecycle

Submission and processing are separate actions. This diagram shows the normal flow:

```mermaid
flowchart LR
  Submit[Submit configuration] --> Quoting
  Quoting --> Quoted
  Quoted -->|Start| Queued
  Queued --> Running
  Running --> Completed
  Quoting --> Failed
  Running --> Failed
```

| Status | What to do |
| --- | --- |
| `Quoting` | Wait for file validation and the quote to finish |
| `Quoted` | Review `batchInfo.estimatedCreditCost`, `totalRows`, and `estimatedRunTime`. Start or change the job |
| `Queued` | Wait for execution to begin, or stop the job |
| `Running` | Read `batchInfo.progress`, or stop the job |
| `Completed` | Retrieve the results from your output destination or `batchInfo.downloadPath` |
| `Failed` | Review the job details and configuration before submitting another job |
| `Cancelled` | The job was stopped. You can change it or restart it, which requotes it before processing |

Polling GET does not start or change a job. Check the status rather than assuming an HTTP `200` means processing succeeded.

## Start automatically

Set `autoStart=true` when submitting the job to queue it after quoting. With the default `false`, review the quote and call `/batch/{batchId}/start` yourself. If there are insufficient credits for automatic start, the job remains `Quoted`.

Starting a quoted job requires sufficient credits for its estimated cost. `batchInfo.executionRate` is assigned by the service for your subscription and reports requests per second. It is informational, not a request setting.

## Update a job

Send the complete configuration to `PUT /batch/{batchId}`. You can change a job in `Quoted` or `Cancelled` status. A changed configuration is validated and moves back to `Quoting`.

```shell
curl --fail-with-body --request PUT \
  "https://api.psma.com.au/v1/batches/batch/$BATCH_ID" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data @batch-request.json
```

Do not include `batchInfo` or `status` as configuration inputs. They describe the job's state. An unchanged configuration returns the existing job without requoting it.

## Stop or restart a job

You can stop a `Quoted`, `Queued`, or `Running` job:

```shell
curl --fail-with-body --request POST \
  "https://api.psma.com.au/v1/batches/batch/$BATCH_ID/stop" \
  -H "Authorization: $GEOSCAPE_API_KEY"
```

The returned status is `Cancelled`. To restart, POST to `/batch/{batchId}/start`. Restarting a cancelled job triggers quoting again and automatic start after the quote.

## Delete jobs

Use `POST /batch/delete` to delete one or more of your jobs. The request body is a JSON array of job IDs, even when deleting just one job. This operation uses POST rather than HTTP DELETE.

- Jobs in `Quoted`, `Completed`, `Failed`, or `Cancelled` status can be deleted
- Jobs in `Quoting`, `Queued`, or `Running` status cannot be deleted. Stop a queued or running job first
- Save any results you need before deleting. Deleted jobs disappear from the public list and return `404` when retrieved by ID
- Deletion removes service-stored input files and, for completed jobs, service-stored output files

```shell
curl --fail-with-body --request POST \
  "https://api.psma.com.au/v1/batches/batch/delete" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  -H "Content-Type: application/json" \
  --data '["063b435f-22ca-43c6-ae1d-e697d50e514a", "09525fb5-6a53-40d1-9188-a661a18f19f8"]'
```

### Check each deletion result

HTTP `200` means the deletion request was processed. Some or all jobs may still have failed. Check `summary.successCount`, `summary.failed`, and the IDs in `details`:

```json
{
  "summary": {"successCount": 1, "failed": 1},
  "details": {
    "successful": ["063b435f-22ca-43c6-ae1d-e697d50e514a"],
    "failed": [
      {
        "code": "400",
        "message": "Jobs can only be deleted in Quoted, Completed or Failed state",
        "count": 1,
        "ids": ["09525fb5-6a53-40d1-9188-a661a18f19f8"]
      }
    ]
  }
}
```

Failures are grouped by string-valued code:

| Code | Meaning | What to do |
| --- | --- | --- |
| `400` | The job's current state does not allow deletion | Wait for quoting to finish, or stop a queued or running job before retrying |
| `403` | `Access forbidden` | Check job ownership and application access |
| `404` | `No job found with this ID` | Check the ID. A previously deleted job also returns this code |

The current `400` message omits `Cancelled`, but cancelled jobs can be deleted. Failure groups can arrive in any order. Retry only the failed IDs after resolving their causes. See [Delete batch jobs](/reference/batches-v1-batches#delete-batch-jobs) for the complete response schema.

## List jobs

`GET /batch` returns `batchJobs` as an array of summaries, rather than full configurations:

```shell
curl --fail-with-body --get \
  "https://api.psma.com.au/v1/batches/batch" \
  -H "Authorization: $GEOSCAPE_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0"
```

- `limit` defaults to 100 and accepts 1 to 1,000
- `offset` defaults to 0
- Follow `links.next` while it is present. Resolve relative links against `https://api.psma.com.au` and include your Authorization header
- Use each summary's `batchInfo.batchId` to retrieve the full configuration

## Review results and costs

- Quote and actual costs are reported in credits through `estimatedCreditCost` and `actualCreditCost`
- Estimated and actual runtimes are duration strings, not timestamps
- `progress` is descriptive text and can change format as the job proceeds
- A completed job with `returnDownloadLink=true` can include `downloadPath`. If it is missing, check `messages` and premium-data access
- A completed job can contain rows with no address match. Assess match quality and mapped output values before accepting them

## Next steps

- [Configure input and output files](/guides/batches/files-and-mappings)
- [Review matching quality](/guides/addresses/assessing-matches)
- [Handle request errors](/guides/errors)