Query | ArcGIS REST APIs | Esri Developer

URL:: https://<root>/<serviceName>/TopographicProductionServer/jobs/query
Methods:: GET
Required Capability:: Requires a Professional or Professional Plus user type account and a Topographic Mapping server extension license.
Version Introduced:: 10.9

Description

The query operation retrieves the status of jobs submitted to the server and returns the status, start date, last modified date, and messages for a set of jobs.

Request parameters

Parameter Details

Parameter	Details
`startDate` (Optional)	Retrieves all of the jobs that started on or after the start date and time if the start date and time is specified. The date and time should be UTC and in ISO 8601 format. It is added to the URL using the following format: YYYY-MM-DDThh:mm:ssZ. If time is not specified, then midnight is used in the following format: 00:00:00.
`endDate` (Optional)	Retrieves all of the jobs that ended on or before the end date and time if the end date and time is specified. The date and time should be UTC and in ISO 8601 format. It is added to the URL using the following format: YYYY-MM-DDThh:mm:ssZ. If time is not specified, then 23:59:59 is used.
`status` (Optional)	Retrieves all the jobs with a particular status if the status parameter and value is specified and appended to the URL, for example, https://< mapservice-url >/TopographicProductionServer/jobs/query?status=5. The `status` parameter supports the following values: `0`—New `1`—Submitted `2`—Waiting `3`—Executing `4`—Succeeded `5`—Failed `6`—TimedOut `7`—Canceling `8`—Canceled `9`—Deleting `10`—Deleted `100`—Paused `101`—Resumed `102`—Pause pending `103`—Resume pending Note This value can be an array of status codes.
`msgLevel` (Optional)	The message level associated with the job. The values are the following: `info` `warn` `error` When constructing a query URL, the `msgLevel` value is added to the end of the URL, for example, `...jobs/job/<jobID>?msgLevel=info` . Note Regardless of the `msgLevel` value, any errors that a job contains are included in the `messages` array of the response by default.
`user` (Optional)	The user name used for account authentication.
`jobType` (Optional)	The integer code value that corresponds to the job type. This can be a single code or an array of codes. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 { Unset = -1, MapProduct = 1, WorkflowTaskGroup = 2, UploadJobData = 3, WorkflowTask = 4, WorkflowMapProduct = 5 };`
`filter` (Optional)	A JSON object for filtering jobs by service, phase, task group, or product version. Properties include `levelOfDetails` (long \| null) to control detail scope, `services` (string[] \| null) for service IDs, `productVersion` (string \| null) for product filtering, `task` (string \| null) for specific task filtering, and `phases` (array \| null) for phase and task group filtering. See the Level of Details section below for information about the `levelOfDetails` property. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 { "levelOfDetails": 1, "services": ["serviceId1", "serviceId2"], "productVersion": "1.0", "task": "taskId", "phases": [ { "phaseId": "phase1", "taskgroups": ["taskgroup1", "taskgroup2"] } ] }`
`spatialExtent` (Optional)	A JSON string representing the coordinates of the area of interest (AOI) extent to filter jobs. Used to retrieve jobs associated with a specific geographic area.
`start` (Optional)	The start index for pagination. Specifies the position from which to begin returning jobs in the result set. Used with the `limit` parameter for paging through results.
`limit` (Optional)	The maximum number of jobs to return in the response. Used with the `start` parameter to implement pagination over large result sets.

startDate

(Optional)

Retrieves all of the jobs that started on or after the start date and time if the start date and time is specified. The date and time should be UTC and in ISO 8601 format. It is added to the URL using the following format: YYYY-MM-DDThh:mm:ssZ. If time is not specified, then midnight is used in the following format: 00:00:00.

endDate

(Optional)

Retrieves all of the jobs that ended on or before the end date and time if the end date and time is specified. The date and time should be UTC and in ISO 8601 format. It is added to the URL using the following format: YYYY-MM-DDThh:mm:ssZ. If time is not specified, then 23:59:59 is used.

status

(Optional)

Retrieves all the jobs with a particular status if the status parameter and value is specified and appended to the URL, for example, https://< mapservice-url >/TopographicProductionServer/jobs/query?status=5. The status parameter supports the following values:

0—New
1—Submitted
2—Waiting
3—Executing
4—Succeeded
5—Failed
6—TimedOut
7—Canceling
8—Canceled
9—Deleting
10—Deleted
100—Paused
101—Resumed
102—Pause pending
103—Resume pending

msgLevel

(Optional)

The message level associated with the job. The values are the following:

info
warn
error

When constructing a query URL, the msgLevel value is added to the end of the URL, for example, ...jobs/job/<jobID>?msgLevel=info .

user

(Optional)

The user name used for account authentication.

jobType

(Optional)

The integer code value that corresponds to the job type. This can be a single code or an array of codes.

Use dark colors for code blocksCopy
{
  Unset = -1,
  MapProduct = 1,
  WorkflowTaskGroup = 2,
  UploadJobData = 3,
  WorkflowTask = 4,
  WorkflowMapProduct = 5
};

filter

(Optional)

A JSON object for filtering jobs by service, phase, task group, or product version. Properties include levelOfDetails (long | null) to control detail scope, services (string[] | null) for service IDs, productVersion (string | null) for product filtering, task (string | null) for specific task filtering, and phases (array | null) for phase and task group filtering. See the Level of Details section below for information about the levelOfDetails property.

Use dark colors for code blocksCopy
{
  "levelOfDetails": 1,
  "services": ["serviceId1", "serviceId2"],
  "productVersion": "1.0",
  "task": "taskId",
  "phases": [
    {
      "phaseId": "phase1",
      "taskgroups": ["taskgroup1", "taskgroup2"]
    }
  ]
}

spatialExtent

(Optional)

A JSON string representing the coordinates of the area of interest (AOI) extent to filter jobs. Used to retrieve jobs associated with a specific geographic area.

start

(Optional)

The start index for pagination. Specifies the position from which to begin returning jobs in the result set. Used with the limit parameter for paging through results.

limit

(Optional)

The maximum number of jobs to return in the response. Used with the start parameter to implement pagination over large result sets.

Level of Details

The levelOfDetails property in the filter parameter controls the scope of information returned for each job:

Value	Name	Description
`1`	Minimal	Returns minimal job information without task group or task details. Suitable for area-of-interest (AOI) retrieval.
`2`	Summary	Returns task group and task information for display in attribute tables.

JSON Response syntax

The following is the syntax of a response:

Use dark colors for code blocksCopy
{
  "count": <the number of jobs that have been returned in the response>,
  "jobs": [
   {
    "status": <untranslated string representing general status of the job>,
    "statusCode": <code representing specific status of the job>,
    "submissionTime": <time and date in UTC and ISO 8601 format of the job submission YYYY-MM-DDThh:mm:ssZ>,
    "lastUpdatedTime": <time and date in UTC and ISO 8601 format of the last job update YYYY-MM-DDThh:mm:ssZ>,
    "percentComplete": <percent of the job completed>,
    "aoiLayer": <URL of AOI layer>,
    "aoiFeatureId": <AOI feature ID>,
    "outputUrl": <URL of output>,
    "user": <username>,
    "jobId": <job identifier>,
    "productName": <name of the product>,
    "productVersion": <version of the product>,
    "outputType": <type/format of the output>,
    "messages": {
     <informative | error | warning>
    }
   },
   ...]
}

Example usage

Query the jobs REST resource to review jobs by start date and message level using the startDate and msgLevel parameters.

Request URL and parameters:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/jobs

Use dark colors for code blocksCopy
f=json
startDate=09-21-2020
msgLevel=info

JSON Response example

The following is an example of a response:

Use dark colors for code blocksCopy
{
 "count": 3
 "jobs": [
  {
   "status": "InProgress",
   "statusCode": 3,
   "submissionTime": "2020-09-21T15:48:22Z",
   "lastUpdatedTime": "2020-09-21T15:48:22Z",
   "percentComplete": 0.052631578947368418,
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user1",
   "jobId": "5F9E1EE1-CB27-48E6-8B11-FEF9B9B281CA",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
    "informative": [
     "Submitted.",
     "Executing..."
     "Start Time: Monday, September 21, 2020 03:48:22 PM",
     "Starting to generate product MTM50.",
     "Start Time: Monday, September 21, 2020 03:48:22 PM",
     "Executing Import Template and Extract Features",
     "Start Time: Monday, September 21, 2020 03:48:22 PM"
    ]
   }
  },
  {
   "status": "Failed",
   "statusCode": 5,
   "submissionTime": "2020-09-21T15:49:14Z",
   "lastUpdatedTime": "2020-09-21T15:49:14Z",
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user2",
   "jobId": "38913E2C-B655-4085-B59F-4A5B0D20224E",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
    "informative": [
     "Submitted.",
     "Executing..."
    ],
    "errors": [
     "ERROR 000824: The tool is not licensed.",
     "Failed."
    ]
   }
  },
  {
   "status": "Pending",
   "statusCode": 2,
   "submissionTime": "2020-09-21T16:17:19Z",
   "lastUpdatedTime": "2020-09-21T16:17:19Z",
   "percentComplete": 0,
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user3",
   "jobId": "91CAF47B-A26F-4F43-ABC7-78DDC3EDBF7A",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
   }
  }
 ]
}

Example usage

Query the jobs REST resource to review jobs by start date with a failed status using the startDate and status parameters.

Request URL and parameters:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/jobs

Use dark colors for code blocksCopy
f=json
startDate=09-21-2020
status=5

JSON Response example

The following is an example of a response:

Use dark colors for code blocksCopy
{
 "count": 3
 "jobs": [
  {
   "status": "Failed",
   "statusCode": 5,
   "submissionTime": "2020-09-21T16:29:32Z",
   "lastUpdatedTime": "2020-09-21T16:29:32Z",
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user1",
   "jobId": "7187043F-C096-4610-9DA9-15469A71DA79",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
    "errors": [
     "ERROR 000824: The tool is not licensed.",
     "Failed."
    ]
   }
  },
  {
   "status": "Failed",
   "statusCode": 5,
   "submissionTime": "2020-09-21T16:29:39Z",
   "lastUpdatedTime": "2020-09-21T16:29:39Z",
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user2",
   "jobId": "4F7D692F-5BD4-4276-9B6B-88818F8B5B39",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
    "errors": [
     "ERROR 000824: The tool is not licensed.",
     "Failed."
    ]
   }
  },
  {
   "status": "Failed",
   "statusCode": 5,
   "submissionTime": "2020-09-21T16:29:44Z",
   "lastUpdatedTime": "2020-09-21T16:29:44Z",
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120733
   "outputUrl":
   "user": "user3",
   "jobId": "36A6CA20-9095-42FF-A4C7-FE3C6AEE8988",
   "productName": "MTM50",
   "productVersion": "Test",
   "outputType": "PDF",
   "messages": {
    "errors": [
     "ERROR 000824: The tool is not licensed.",
     "Failed."
    ]
   }
  }
 ]
}

Example usage

Query the jobs REST resource by filtering for jobs from specific services and product versions using the filter, start, and limit parameters for pagination.

Request URL and parameters:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/jobs/query

Use dark colors for code blocksCopy
f=json
filter={"levelOfDetails": 2, "services": ["serviceId1", "serviceId2"], "productVersion": "1.0"}
start=0
limit=10

JSON Response example

The following is an example of a paginated response showing the first 10 jobs filtered by service and product version with task group details:

Use dark colors for code blocksCopy
{
 "count": 10,
 "jobs": [
  {
   "status": "Succeeded",
   "statusCode": 4,
   "submissionTime": "2024-02-15T09:30:00Z",
   "lastUpdatedTime": "2024-02-15T10:15:30Z",
   "percentComplete": 100,
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120845,
   "outputUrl": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/output/job123",
   "user": "user1",
   "jobId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
   "productName": "MTM50",
   "productVersion": "1.0",
   "outputType": "PDF",
   "messages": {
    "informative": [
     "Submitted.",
     "Processing workflow tasks...",
     "Completed task group: TaskGroup1"
    ]
   }
  },
  {
   "status": "Succeeded",
   "statusCode": 4,
   "submissionTime": "2024-02-15T08:45:00Z",
   "lastUpdatedTime": "2024-02-15T09:20:00Z",
   "percentComplete": 100,
   "aoiLayer": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/5",
   "aoiFeatureId": 120846,
   "outputUrl": "https://organization.example.com/<context>/rest/services/SampleService/TopographicProductionServer/output/job124",
   "user": "user2",
   "jobId": "F5E4D3C2-B1A0-9876-5432-ABCDEF123456",
   "productName": "MTM50",
   "productVersion": "1.0",
   "outputType": "GeoTIFF",
   "messages": {
    "informative": [
     "Submitted.",
     "Processing workflow tasks...",
     "Completed task group: TaskGroup2"
    ]
   }
  }
 ]
}