Task operation: execute

This topic describes the interaction between the client and server (local or remote) when using the execute execution type. Developers use the API classes and methods to manage this interaction.

How to execute the task

To execute a geoprocessing task, the client must construct a request URL with the Execute task URL and append name-value pairs of all the required input parameters of the task as shown below:


parameter1=value1 is a name-value pair where parameter1 is the name of the task parameter and value1 is the ASCII representation of the JSON value. When the request URL is sent to the server, the task runs on the server with the given input values. At the end of execution, if the task succeeds the server will construct a response with the values of the output parameters and will send it to the client as illustrated below. If the task fails, the server will send an error response to the client.

Execute task at the server

Successful task result

The response sent by the client is called a geoprocessing task result and includes the output parameter values and messages generated by the geoprocessing task during execution. The task result will have an array of output parameters. Each output parameter in the array will have a paramName, dataType, and its value. The task result will also have an array of geoprocessing messages. Each element in the message array will have a type (esriJobMessageTypeInformative, esriJobMessageTypeWarning, or esriJobMessageTypeError) and a message description. The messages returned by the server depends on the message level of the geoprocessing service. If the message level is set to None, the server will not return any messages.

Learn more about message levels in geoprocessing services

The task result JSON for a Buffer Points task with one output parameter, Output_Polygons, is shown below.

JSON representation of geoprocessing task result. (The geometry and message array values have been truncated in the example for brevity.)

  {"paramName": "Output_Polygons",
   "dataType": "GPFeatureRecordSetLayer",
    "displayFieldName": "",
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {"wkid": 102726,"latestWkid": 102726},
    "fields":[{"name": "FID","type": "esriFieldTypeOID","alias": "FID"},
              {"name": "BUFF_DIST","type": "esriFieldTypeDouble","alias": "BUFF_DIST"},
              {"name": "Shape_Length","type": "esriFieldTypeDouble","alias": "Shape_Length"},
              {"name": "Shape_Area","type": "esriFieldTypeDouble","alias": "Shape_Area"},
    "features": [{"attributes": {"FID": 1,"BUFF_DIST": 3280.83333333,"Shape_Length": 20613.401930152133,
    "Shape_Area": 3.381121258723078E7},
    "geometry": {"rings": [[[7643591.49993746,684676.8331969529],[7643683.927544728,684675.5310036689],...more]]},        
    "exceededTransferLimit": false
 "messages": [{"type":"esriJobMessageTypeInformative","description": "Start Time: Mon Feb 27 15:56:09 2012"},
              {"type":"esriJobMessageTypeInformative","description": "Executing (BufferPoints): BufferPoints.. "}...more

Error response

An execute task operation may fail because of invalid parameters or other geoprocessing tool failures. In such cases, the server will return a geoprocessing task error with a code number, the string Unable to complete operation., and details of the failure. The JSON format for the error is given below:

Error JSON returned by a geoprocessing task

{"error":{"code":400,"message":"Unable to complete operation.","details":[]}}

The level of detail in the error response depends on the message level of the geoprocessing service. Based on the message level, the details property will include appropriate geoprocessing tool messages generated during execution. If the input parameters of the tool are invalid or if the message level property of the geoprocessing service is set to None, the details property of the error response will be empty as shown in above example.


The cancel operation is not supported for the execute operation. It is only supported for submitJob operation.

In this topic
  1. How to execute the task