Search tasks

POST 
/v1/tasks/search

Returns the list of tasks that satisfy search request params.

• If an empty body is provided, all tasks are returned.
• Only one of [searchAfter, searchAfterOrEqual, searchBefore, searchBeforeOrEqual] search options must be present in request.

Request

application/json

Body

state string

Possible values: [CREATED, COMPLETED, CANCELED, FAILED]

The state of the tasks.

assigned boolean

Are the tasks assigned?

assignee string

Who is assigned to the tasks?

assignees string[]

The assignee is one of the given assignees.

taskDefinitionId string

What's the BPMN flow node?

candidateGroup string

Given group is in candidate groups list.

candidateGroups string[]

At least one of the given groups is in candidate groups list.

candidateUser string

Given user is in candidate user list.

candidateUsers string[]

At least one of the given users is in candidate user list.

processDefinitionKey string

Reference to process definition (renamed equivalent of TaskQuery.processDefinitionId field).

processInstanceKey string

Reference to process instance (renamed equivalent of TaskQuery.processInstanceId field)

pageSize int32

Size of tasks page (default = 50).

followUpDate object

A range of due dates for the tasks to search for.

from date-time

Start date range to search from in date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard.

to date-time

End date range to search to in date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard.

dueDate object

A range of due dates for the tasks to search for.

from date-time

Start date range to search from in date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard.

to date-time

End date range to search to in date-time format outlined in section 5.6 of the RFC 3339 profile of the ISO 8601 standard.

taskVariables object[]
An array of filter clauses specifying the variables to filter for.
If defined, the query returns only tasks to which all clauses apply.
However, it's important to note that this filtering mechanism is
designed to work exclusively with truncated variables. This means
variables of a larger size are not compatible with this filter, and
attempts to use them may result in inaccurate or incomplete query results.
Array [
name string
The name of the variable.
value string
The value of the variable. When specifying the variable value, it's crucial to maintain consistency with JSON values (serialization for the complex objects such as list) and ensure that strings remain appropriately formatted.
operator string
Possible values: [eq]
The comparison operator to use for the variable.
* eq: Equals
]
tenantIds string[]

An array of Tenant IDs to filter tasks. When multi-tenancy is
enabled, tasks associated with the specified tenant IDs are returned;
if disabled, this parameter is ignored.

sort object[]
An array of objects specifying the fields to sort the results by.
Array [
field string
Possible values: [completionTime, creationTime, followUpDate, dueDate]
order string
Possible values: [ASC, DESC]
• ASC: Ascending
  * DESC: Descending
]
searchAfter string[]

Used to return a paginated result. Array of values that should be copied from sortValues of one of the tasks from the current search results page.
It enables the API to return a page of tasks that directly follow the task identified by the provided values, with respect to the sorting order.

searchAfterOrEqual string[]

Used to return a paginated result. Array of values that should be copied from sortValues of one of the tasks from the current search results page.
It enables the API to return a page of tasks that directly follow or are equal to the task identified by the provided values, with respect to the sorting order.

searchBefore string[]

Used to return a paginated result. Array of values that should be copied from sortValues of one of the tasks from the current search results page.
It enables the API to return a page of tasks that directly precede the task identified by the provided values, with respect to the sorting order.

searchBeforeOrEqual string[]

Used to return a paginated result. Array of values that should be copied from sortValues of one of the tasks from the current search results page.
It enables the API to return a page of tasks that directly precede or are equal to the task identified by the provided values, with respect to the sorting order.

includeVariables object[]
An array used to specify a list of variable names that should be included in the response when querying tasks.
This field allows users to selectively retrieve specific variables associated with the tasks returned in the search results.
Array [
name string
The name of the variable.
alwaysReturnFullValue boolean
Default value: false
Always return the full value of the variable?
]
implementation string

Possible values: [JOB_WORKER, ZEEBE_USER_TASK]

Responses

200

On success returned.

application/json

Schema

Schema

• Array [
id string

The unique identifier of the task.

name string

The name of the task.

taskDefinitionId string

User Task ID from the BPMN definition.

processName string

The name of the process.

creationDate string

When was the task created (renamed equivalent of Task.creationTime field).

completionDate string

When was the task completed (renamed equivalent of Task.completionTime field).

assignee string

The username/id of who is assigned to the task.

taskState string

Possible values: [CREATED, COMPLETED, CANCELED, FAILED]

The state of the task.

sortValues string[]

Array of values to be copied into TaskSearchRequest to request for next or previous page of tasks.

isFirst boolean

A flag to show that the task is first in the current filter.

formKey string

Reference to the task form.

formId string

Reference to the ID of a deployed form. If the form is not deployed, this property is null.

formVersion int64

Reference to the version of a deployed form. If the form is not deployed, this property is null.

isFormEmbedded boolean

Is the form embedded for this task? If there is no form, this property is null.

processDefinitionKey string

Reference to process definition (renamed equivalent of Task.processDefinitionId field).

processInstanceKey string

Reference to process instance id (renamed equivalent of Task.processInstanceId field).

tenantId string

The tenant ID associated with the task.

dueDate date-time

The due date for the task.

followUpDate date-time

The follow-up date for the task.

candidateGroups string[]

The candidate groups for the task.

candidateUsers string[]

The candidate users for the task.

variables object[]
An array of the task's variables. Only variables specified in TaskSearchRequest.includeVariables are returned. Note that a variable's draft value is not returned in TaskSearchResponse.
Array [
id string
The unique identifier of the variable.
name string
The name of the variable.
value string
The value of the variable.
isValueTruncated boolean
Does the previewValue contain the truncated value or full value?
previewValue string
A preview of the variable's value. Limited in size.
draft object
The draft value of the variable.
value string
The value of the variable.
isValueTruncated boolean
Does the previewValue contain the truncated value or full value?
previewValue string
A preview of the variable's value. Limited in size.
]
implementation string

Possible values: [JOB_WORKER, ZEEBE_USER_TASK]

• ]

Example (from schema)

[
  {
    "id": "string",
    "name": "string",
    "taskDefinitionId": "string",
    "processName": "string",
    "creationDate": "string",
    "completionDate": "string",
    "assignee": "string",
    "taskState": "CREATED",
    "sortValues": [
      "string"
    ],
    "isFirst": true,
    "formKey": "string",
    "formId": "string",
    "formVersion": 0,
    "isFormEmbedded": true,
    "processDefinitionKey": "string",
    "processInstanceKey": "string",
    "tenantId": "string",
    "dueDate": "2024-04-03T03:24:08.865Z",
    "followUpDate": "2024-04-03T03:24:08.865Z",
    "candidateGroups": [
      "string"
    ],
    "candidateUsers": [
      "string"
    ],
    "variables": [
      {
        "id": "string",
        "name": "string",
        "value": "string",
        "isValueTruncated": true,
        "previewValue": "string",
        "draft": {
          "value": "string",
          "isValueTruncated": true,
          "previewValue": "string"
        }
      }
    ],
    "implementation": "JOB_WORKER"
  }
]

400

An error is returned when more than one search parameters among [searchAfter, searchAfterOrEqual, searchBefore, searchBeforeOrEqual] are present in request

application/problem+json

Schema

Schema

status int32

An integer that represents the HTTP status code of the error response. For example, 400 indicates a 'Bad Request' error, 404 indicates a 'Not Found' error, and so on.

message string

A string that provides a brief description of the error that occurred.

instance string

Error instance UUID for lookup (e.g., in log messages).

Example (from schema)

{
  "status": 0,
  "message": "string",
  "instance": "string"
}

Loading...