List matching jobs
Request accessPurpose
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/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" \ -H "X-Version: 1"Request parameters
| Parameter | Required | Description | Value |
|---|---|---|---|
job_type | Yes | Type of job | ROAD_MATCHING |
Request headers
| Header | Required | Description |
|---|---|---|
tomtom-api-key | Yes | Your TomTom API key |
Authorization | Yes | Bearer token from Azure CLI |
X-Version | Yes | API version (use 1) |
Response data
Response example
{ "jobs": [ { "jobRunId": "job-abc123", "storageId": "storage-001", "inputFileName": "roads_data.parquet", "outputFileName": "roads_data_matched.parquet", "matchingType": "road", "overtureRelease": "<latest-overture-release>", "status": "finished", "createdAt": "2026-01-20T10:00:00Z", "modifiedAt": "2026-01-20T10:15:00Z" }, { "jobRunId": "job-def456", "storageId": "storage-001", "inputFileName": "places_data.parquet", "matchingType": "road", "overtureRelease": "<latest-overture-release>", "status": "running", "createdAt": "2026-01-21T14:30:00Z", "modifiedAt": "2026-01-21T14:30:00Z" } ]}Response fields
| Field | Type | Description |
|---|---|---|
jobs | array | List of job objects |
jobs[].jobRunId | string | Unique identifier for the job |
jobs[].storageId | string | Storage where files are located |
jobs[].inputFileName | string | Name of the input file |
jobs[].outputFileName | string | Name of output file (when available) |
jobs[].matchingType | string | Type of matching performed |
jobs[].overtureRelease | string | Overture Maps release version used |
jobs[].status | string | Current job status |
jobs[].createdAt | string | ISO 8601 timestamp of job creation |
jobs[].modifiedAt | string | ISO 8601 timestamp of last update |
Job status values
| Status | Description |
|---|---|
queued | Job is waiting to be processed |
running | Job is currently being executed |
finished | Job completed successfully |
failed | Job encountered an error |
cancelled | Job was cancelled by user |
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 |