Job status

After a job has been submitted, the job status can be checked with a GET request on the jobId GET https://batch.search.hereapi.com/v7/batch/jobs/<jobId>.

The job status can be one of the following messages:

submitted
queued
pending
inProgress
completed
failure
stopped
deleted

The response of related action endpoints like submitted, start or delete is a subset of this full status.

Job submitted

status = submitted created shows the time the job was created.

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "submitted",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "records": {
    "total": 6,
    "valid": 0,
    "invalid": 0,
    "processed": 0,
    "pending": 0,
    "succeeded": 0,
    "failed": 0
  },
  "resultsHref": "",
  "errorsHref": "",
  "outputType": "csv"
}

A job is submitted via POST (upload of the input data) and started right away by default.

A job can also be submitted without starting it immediately.

To do this, specify the parameter startJob=false. Start the job later with a PUT https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/start.

Job started

status = queued

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "queued",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "records": {
    "total": 6,
    "valid": 0,
    "invalid": 0,
    "processed": 0,
    "pending": 0,
    "succeeded": 0,
    "failed": 0
  },
  "resultsHref": "",
  "errorsHref": "",
  "outputType": "csv"
}

A job can be queued if the current user has too many running jobs or if there are too many running jobs in the system over all.

All jobs move to queued state after they are started. But they may stay there only very shortly and it may be hard to catch this state. [//]: # (QUESTION: @Christian - please check this compared to related line in inProgress) The created timestamp is set.

In this state the total counter is an estimate. It may change later on if there is a header or empty lines.

Job is started via PUT /batch/jobs/<jobId>/start

Job is pending

status = pending

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "pending",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "records": {
    "total": 6,
    "valid": 0,
    "invalid": 0,
    "processed": 0,
    "pending": 0,
    "succeeded": 0,
    "failed": 0
  },
  "resultsHref": "",
  "errorsHref": "",
  "outputType": "csv"
}

Job is pending, it is prepared for execution.

Job is in progress

status = inProgress

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "inProgress",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "started": "2025-08-04T16:50:21.859527Z",
  "records": {
    "total": 5,
    "valid": 5,
    "invalid": 0,
    "processed": 0,
    "pending": 5,
    "succeeded": 0,
    "failed": 0
  },
  "resultsHref": "",
  "errorsHref": "",
  "outputType": "csv"
}

The started timestamp is set when the job transitions into inProgress state.

The total counter reflects the correct value now. The other record counts reflect job progress.

Job is completed successfully

status = completed

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "completed",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "started": "2025-08-04T16:50:21.859527Z",
  "ended": "2025-08-04T16:50:44.726596Z",
  "records": {
    "total": 5,
    "valid": 5,
    "invalid": 0,
    "processed": 5,
    "pending": 0,
    "succeeded": 5,
    "failed": 0
  },
  "resultsHref": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/results",
  "errorsHref": "",
  "outputType": "csv"
}

The ended timestamp is set when the job transitions into completed state. [//]: # (QUESTION: @Christian - please check this) Record counts show stats for job.

sum of valid and invalid is equal to total
processed is equal to valid
sum of succeeded and failed is qual to processed
pending is zero

resultsHref and errorsHref are set. If one of both is empty, there are no results or errors.

Job is stopped

status = stopped

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "stopped",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "started": "2025-08-04T16:50:21.859527Z",
  "ended": "2025-08-04T16:50:44.726596Z",
  "records": {
    "total": 5,
    "valid": 5,
    "invalid": 0,
    "processed": 3,
    "pending": 0,
    "succeeded": 3,
    "failed": 0
  },
  "resultsHref": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/results",
  "errorsHref": "",
  "outputType": "csv"
}

Similar to completed jobs, the ended timestamp is set when the job transitions into stopped state.

In contrast to completed jobs, the processed counter is less than valid counter as the processing has been interrupted.

Job is deleted

status = deleted

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "deleted",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "started": "2025-08-04T16:50:21.859527Z",
  "ended": "2025-08-04T16:50:44.726596Z",
  "records": {
    "total": 5,
    "valid": 5,
    "invalid": 0,
    "processed": 5,
    "pending": 0,
    "succeeded": 5,
    "failed": 0
  },
  "resultsHref": "",
  "errorsHref": "",
  "outputType": "csv"
}

Job was deleted by user with DELETE /batch/jobs/<jobId>.

Record counts show stats for job at time of deletion. If the job had not been started at the time of deletion, no record counts are shown.

Job results are not available for download anymore.

Files are removed from the Geocoder's systems. Note: Jobs are automatically removed from the server 30 days after they are processed.

Job failed

status = failure

{
  "id": "<jobId>",
  "serviceHrn": "hrn:here:service::olp-here:search-geocode-7",
  "billingTags": [],
  "status": "failure",
  "href": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>",
  "created": "2025-08-04T16:48:36.209077Z",
  "started": "2025-08-04T16:50:21.859527Z",
  "ended": "2025-08-04T16:50:44.726596Z",
  "records": {
    "total": 6,
    "valid": 0,
    "invalid": 6,
    "processed": 0,
    "pending": 0,
    "succeeded": 0,
    "failed": 6
  },
  "resultsHref": "",
  "errorsHref": "https://batch.search.hereapi.com/v7/batch/jobs/<jobId>/errors"
}

Job failed while running. This is unusual and caused by an internal error. You can review the error messages. When we have fixed the root cause of the error, you can restart the job.