Search tasks

Abstract

Learn how to search tasks with the API to return task lists using filters, sorting, and pagination.

Use the POST /tasks/search endpoint to retrieve a paginated list of tasks that match your criteria. This endpoint supports filtering, sorting, and pagination, making it suitable for building task lists, dashboards, and operational views.

Request

To retrieve a paginated list of tasks, send a POST request to the /tasks/search endpoint.

Parameters

This endpoint has five optional body parameters.

Field	Type	Description
`filter_model`	any	The `filter_model` structure supports text, number, set, and date filters, including combined conditions. See Task search filter model structure for full details and examples. Filtering is optional. If no filtering is required, you can either omit the `filter_model` parameter or set it to `null`.
`max_page_size`	integer or null	Defines the maximum number of results returned per page. Defaults to 50.
`page_token`	string or null	Enter the `next_page_token` from the previous response to return the next page of results.
`sorting_field`	string	Sorts the list of tasks in the response by this field. The possible values are: `TASK_ID`, `CREATED_AT`, `ENTITY_ID`, `ASSESSMENT_ID`, `STATUS`, `ASSIGNED_TO_ID`
`sorting_type`	string	The direction of sorting to apply to the sorting field. The possible values are: `ASC`, `DESC`

Sample request

This example searches for tasks with sorting applied.

curl --request "POST" \
 "https://{api_region}/v5/tasks/search" \ 
 --header "apikey: API_KEY" \ 
 --header "Content-Type: application/json" \ 
 --data "{  
  "filter_model": null,  
  "max_page_size": 50,  
  "page_token": null,  
  "sorting_field": "TASK_ID",  
  "sorting_type": "ASC" 
 }"

Replace {api_region} with the domain from your region's base URL.

To authenticate your request, include the apikey: YOUR_API_KEY header. See Manage API keys for more information.

Response

A successful request returns a list of task objects and, if more results are available, a token for the next page.

{ 
 "items": [{    
  "assessment_id": "9f60a03f-b3de-4b19-9361-0380d9aa1e9e",
  "assessment_template_id": "af8498c1-32bd-4453-b407-761eb6440e9b",
  "assignment": {   
     "assigned_by_id": "22930149-1fab-4145-94b5-af2031b8de65",
     "assigned_to_id": "73c0fde6-eb34-47d5-8ccc-1b1d0aa325b6",
     "assigned_to_type": "USER",
     "assignment_comment": null
  },      
  "c_name": "Review documentation",  
  "created_at": "2019-08-24T14:15:22Z",
  "custom_metadata": null,
  "data_version": 0,
  "entity_id": "c75f2c73-5ae4-4f1c-99c0-fc726cd41798",
  "id": "8161163a-f227-466f-bc01-090a01e80165",
  "institution_id": "c75f2c73-5ae4-4f1c-99c0-fc726cd41798",
  "locked_at": "2019-08-24T14:15:22Z",
  "microfrontend_id": "f1ea2a19-6836-4b1f-824d-8a04dfae4cc7",
  "name": null,
  "status": "INPROGRESS",
  "step_name": "Review",   
  "updated_at": "2019-08-24T14:15:22Z",   
  "workflow_instance_id": "46ff49d0-5f69-46b0-9de7-5703639a02ce"
 }], 
 "next_page_token": "eyJwYWdlIjoyfQ=="
}

Pass the value in next_page_token as page_token in the next request to retrieve the next page of task objects.

Troubleshooting

If you receive a 401 Unauthorized response, make sure the apikey header is included and contains a valid key. Check that you are using the correct base URL for your region, and if IP allow listing is enabled, verify your request originates from an allowed IP address.

For a full list of the possible error codes, view the API reference.