List matching jobs

Request access

Purpose

Retrieve a list of all matching jobs in your account, including their statuses and metadata.

Request data

HTTP method: `GET`

See the following Query parameters section with the required and optional parameters tables for these values.

URL format

get

URL format

1
https://api.tomtom.com/maps/orbis/platform/gem/jobs

URL example

get

URL example

1
https://api.tomtom.com/maps/orbis/platform/gem/jobs?job_type=ROAD_MATCHING

curl command example

get

curl command example

1
curl -X GET "https://api.tomtom.com/maps/orbis/platform/gem/jobs?job_type=ROAD_MATCHING" \
2
  -H "tomtom-api-key: YOUR_API_KEY" \
3
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Request headers

Header	Required	Description
`tomtom-api-key`	Yes	Your TomTom API key
`Authorization`	Yes	Bearer token from Azure CLI

Query parameters

Parameter	Required	Description	Value
`job_type`	Yes	Type of job	`ROAD_MATCHING` or `LANE_LEVEL_MATCHING`

Response data

Response example

1
{
2
  "job_runs": [
3
    {
4
        "job_type": "ROAD_MATCHING",
5
        "overture_release": "2026-01-21.0",
6
        "input_filename": "test_data.parquet",
7
        "job_id": 123456789,
8
        "requested_at": "2026-02-18T10:38:59.031762Z",
9
        "result_filename": null,
10
        "statistics": null,
11
        "error_messages": null,
12
        "status": "REQUESTED",
13
        "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
14
    },
15
    {
16
        "job_type": "LANE_LEVEL_MATCHING",
17
        "input_filename": "test_data.parquet",
18
        "job_id": 987654321,
19
        "requested_at": "2026-02-18T10:38:59.031762Z",
20
        "result_filename": null,
21
        "statistics": null,
22
        "error_messages": null,
23
        "status": "REQUESTED",
24
        "storage_id": "9b2f6c1d-3e8a-4f5b-a1c7-d4e9f0b3a625"
25
    }
26
  ]
27
}

Response fields

Field	Type	Description
`job_runs`	array	List of job run objects
`job_runs[].job_id`	integer (int64)	Unique identifier for the job
`job_runs[].storage_id`	string (uuid)	Storage where input/output files are located
`job_runs[].input_filename`	string	Name of the input file
`job_runs[].result_filename`	string	Name of the output file. `null` until `status` is `SUCCESS`
`job_runs[].job_type`	string	Type of matching performed
`job_runs[].overture_release`	string	Overture Maps release version for `ROAD_MATCHING` jobs, see Releases
`job_runs[].status`	string	Current job status. See Job status values
`job_runs[].requested_at`	string	ISO 8601 timestamp of job creation
`job_runs[].statistics`	object	Matching statistics. `null` unless `status` is `SUCCESS`
`job_runs[].error_messages`	string[]	List of error messages describing why the job failed. `null` unless `status` is `FAILED`

statistics field is always null for /gem/jobs endpoint, use GET /gem/jobs/{job_id} to retrieve statistics for a specific job when it is completed.

Job status values

Status	Description
`REQUESTED`	Job was requested and is waiting to be processed
`IN_PROGRESS`	Job has started and is currently being executed
`FAILED`	Job encountered an error during the execution
`SUCCESS`	Job finished successfully
`CANCELED`	Job was canceled before completion

Error responses

HTTP Status	Error	Cause	Solution
401	Unauthorized	Invalid credentials	Refresh API key or token
403	Forbidden	Insufficient permissions	Check your access rights
500	Internal Server Error	Server-side issue	Retry the request

List matching jobs

Purpose

Request data

HTTP method: GET

URL format

URL example

curl command example

Request headers

Query parameters

Response data

Response example

Response fields

Job status values

Error responses

HTTP method: `GET`