List matching jobs
Purpose
Retrieve a list of all matching jobs in your account, including their statuses and metadata.
Request data
HTTP method: GET
- Constants and parameters enclosed in curly brackets
{}must be replaced with their values. - See the following Request 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/jobs
URL example
get
URL example
https://api.tomtom.com/maps/orbis/platform/gem/jobs?job_type=ROAD_MATCHING
curl command example
get
curl command example
1curl -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 parameters
| Parameter | Required | Description | Value |
|---|---|---|---|
job_type | Yes | Type of job | ROAD_MATCHING or LANE_LEVEL_MATCHING |
Request headers
| Header | Required | Description |
|---|---|---|
tomtom-api-key | Yes | Your TomTom API key |
Authorization | Yes | Bearer token from Azure CLI |
Response data
Response example
1{2 "jobs": [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 "status": "REQUESTED",12 "storage_id": "storage-001"13 },14 {15 "job_type": "LANE_LEVEL_MATCHING",16 "orbis_version": "123456.1",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 "status": "REQUESTED",23 "storage_id": "storage-002"24 }25 ]26}
Response fields
| Field | Type | Description |
|---|---|---|
jobs | array | List of job objects |
jobs[].job_id | integer | Unique identifier for the job |
jobs[].storage_id | string | Storage where input/output files are located |
jobs[].input_filename | string | Name of the input file |
jobs[].job_type | string | Type of matching performed |
jobs[].overture_release | string | Overture Maps release version for ROAD_MATCHING job type, see Releases |
jobs[].orbis_version | string | Orbis Map version for LANE_LEVEL_MATCHING job type with format <LAYER_ID>.<REVISION>, example 123456.1 |
jobs[].status | string | Current job status (REQUESTED) |
jobs[].requested_at | string | ISO 8601 timestamp of job creation |
jobs[].statistics | object | Matching statistics, available only when status is SUCCESS |
Note: statistics field is always null for /gem/jobs endpoint, use GET /gem/jobs/{jobRunId} 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 |
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 |