On this page

Copy page

Documentation

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:

Code
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.

Code
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:

Code
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

Code
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:

Code
{
  "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 for the complete response schema.

List jobs

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

Code
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
• Review matching quality
• Handle request errors