Task Inventory API

Retrieves detailed metadata and deployment information for specific agent management tasks using their unique task IDs.

The Task Inventory API is designed for efficient data retrieval using a two-step pattern. First, retrieve a list of task IDs via the search endpoint, then use the POST method to fetch comprehensive details for those specific IDs.

HTTP Request

Method: POST

URL: /controller/restui/agent-management/inventory/tasks/ids

Request Headers

Header Required Description
Content-Type Yes Request body format. The value must be application/json.
Accept No Response format. The value must be application/json.
Cookie Yes Valid session cookies for Controller authentication.

Request Body Parameters

Field Type Required Description
requestFilter List<Long> Yes An array of unique task IDs to retrieve.
Note: The value for this field must not be null or empty.
resultColumns List<String> Yes Specifies which fields to return. For example, ID, NAME, TYPE, DEPLOYMENTS.
offset Integer No Pagination starting position. Default is 0.
limit Integer No Maximum number of results to return. Default is 100. For unlimited results, specify -1.
searchFilters List<SearchFilter> No Additional search criteria. The value can be empty for ID-based queries.
columnSorts List<ColumnSort> No Sorting criteria. Mostly empty for ID-based queries.
timeRangeStart long No Start timestamp for time-range filtering. Specified in epoch milliseconds.
timeRangeEnd long No End timestamp for time-range filtering. Specified in epoch milliseconds.

Response Structure

The response returns a 200 OK status with a JSON object containing an array of task details.

Field Type Description
data Array List of UiTaskV2 objects containing requested metadata.
totalCount Long The total number of tasks returned in the current request.

Ui

Example Request

BASH 
curl -X POST 'https://<controller-host>/controller/restui/agent-management/inventory/tasks/ids' \
  -H 'Content-Type: application/json' \
  --cookie 'JSESSIONID=ABC123XYZ' \
  -d '{
    "requestFilter": [284, 283],
    "resultColumns": ["ID", "NAME", "TYPE", "CREATE_TS", "DEPLOYMENTS"],
    "offset": 0,
    "limit": 10
  }'

Error Codes

Status Code Description
400 Bad Request Invalid request structure or empty requestFilter.
403 Forbidden User lacks permission to access tasks for the associated account.
500 Internal Error An unexpected server-side error occurred.