List matching jobs
Request accessPurpose
Retrieve the matching jobs of one job type that you submitted, on storages you can access, with their statuses, statistics, 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
https://api.tomtom.com/maps/orbis/platform/gem/jobsURL example
get
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobs?job_type=ROAD_MATCHINGcurl command example
get
curl command example
curl -X GET "https://api.tomtom.com/maps/orbis/platform/gem/jobs?job_type=ROAD_MATCHING" \ -H "tomtom-api-key: YOUR_API_KEY" \ -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
{ "job_runs": [ { "job_type": "ROAD_MATCHING", "overture_release": "2026-01-21.0", "input_filename": "test_data.parquet", "job_id": 123456789, "requested_at": "2026-02-18T10:38:59.031762Z", "result_filename": null, "statistics": null, "error_messages": null, "status": "REQUESTED", "storage_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, { "job_type": "LANE_LEVEL_MATCHING", "input_filename": "test_data.parquet", "job_id": 987654321, "requested_at": "2026-02-18T10:38:59.031762Z", "result_filename": null, "statistics": null, "error_messages": null, "status": "REQUESTED", "storage_id": "9b2f6c1d-3e8a-4f5b-a1c7-d4e9f0b3a625" } ]}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 | Path of the results file in the storage. 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 of successful ROAD_MATCHING jobs, see Get job details. Otherwise null |
job_runs[].error_messages | string[] | List of error messages describing why the job failed. null unless status is FAILED |
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. See error_messages |
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 | The API key isn’t enabled for the GEM APIs | Enable the GEM APIs on your key, see Obtaining a TomTom API key |
| 500 | Internal Server Error | Server-side issue | Retry the request |