Search element instances

POST

/v2/element-instances/search

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/element-instances/search"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"filter\": { \"processInstanceKey\": \"2251799813685249\", \"state\": \"ACTIVE\" } }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/element-instances/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"filter":{"processInstanceKey":"2251799813685249","state":"ACTIVE"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:8080/v2/element-instances/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "processInstanceKey": "2251799813685249", "state": "ACTIVE" } }'

Available inEmbeddedBundledCluster

AuthAuthenticated Bearer token or console session with X-CSRF-Token · requires history:read

Lists the element instances of the caller’s tenant, across its process instances; name a processInstanceKey to see one instance’s. Every filter takes a plain value or an object of operators, except type, incidentKey and elementInstanceScopeKey, which take a plain value. An element with an open incident has hasIncident and its incidentKey. Nothing matching answers an empty page. Sort by any 8.9 sort field; page with page.after or page.from.

Authorizations

Parameters

Header Parameters

x-tenant-id

string

>= 1 characters

Tenant selection. A principal bound to one tenant may omit it; if sent, it must equal that tenant (403 otherwise). A principal that may act in several tenants must send it on every request: without it the request is refused with 400, and a tenant it may not act in is refused with 403.

Request Body^required

application/json

object

filter

object

processInstanceKey

Any of:

string

elementInstanceKey

Any of:

string

processDefinitionKey

Any of:

string

processDefinitionId

Any of:

string

elementId

Any of:

string

elementName

Any of:

string

type

The BPMN element type (for example SERVICE_TASK).

string

state

Any of:

string

hasIncident

boolean

incidentKey

Any of:

string
integer

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

startDate

Any of:

string

endDate

Any of:

string

elementInstanceScopeKey

Any of:

string
integer

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

tenantId

Any of:

string

sort

Sorted by these properties in turn; a missing value sorts last.

Array<object>

object

field

required

string

Allowed values: elementInstanceKey processInstanceKey processDefinitionKey processDefinitionId startDate endDate elementId elementName type state incidentKey tenantId

order

string

default: ASC

Allowed values: ASC DESC

page

limit (at most 500, default 100) with after (the endCursor of the previous page) or from (an offset). With a sort or a from, every match is sorted and paged by position, and endCursor continues that order. before is not supported.

object

limit

integer

default: 100 >= 1 <= 500

from

integer

after

The endCursor of the previous page.

string

before

Not supported. Any value is rejected with 400.

string

Example

{
  "filter": {
    "processInstanceKey": "2251799813685249",
    "state": "ACTIVE"
  }
}

Responses

200

The matching element instances.

application/json

object

items

required

Array<object>

object

processDefinitionId

required

string

startDate

required

An RFC 3339 timestamp.

string format: date-time

endDate

required

Any of:

string
null

An RFC 3339 timestamp.

string format: date-time

elementId

required

string

elementName

required

Element names are not retained.

string

type

required

The BPMN element type, for example SERVICE_TASK.

string

state

required

string

Allowed values: ACTIVE COMPLETED TERMINATED

hasIncident

required

boolean

tenantId

required

string

elementInstanceKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

processInstanceKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

rootProcessInstanceKey

required

Part of the wire shape. This release always sends null.

null

processDefinitionKey

required

Positive signed 64-bit entity key, written as a decimal string.

string

/^[1-9][0-9]*$/

incidentKey

required

Part of the wire shape. This release always sends null.

null

page

required

totalItems counts every match of the query across all pages, and hasMoreTotalItems is always false. Every page with items carries both cursors; paging with page.after = endCursor ends with an empty page.

object

totalItems

required

integer format: int64

hasMoreTotalItems

required

boolean

startCursor

required

Opaque, base64. Set on every page with items; null only on an empty page.

string | null format: base64

endCursor

required

Opaque, base64. Set on every page with items; pass it as page.after for the next page, which is empty once every item was seen. null only on an empty page.

string | null format: base64

Example

{
  "items": [
    {
      "elementName": "",
      "state": "ACTIVE",
      "hasIncident": false,
      "elementInstanceKey": "2251799813685249",
      "processInstanceKey": "2251799813685249",
      "processDefinitionKey": "2251799813685249"
    }
  ]
}

400

The request is malformed, or it uses a property or filter this release does not support.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:invalid-argument",
  "title": "Bad Request",
  "status": 400,
  "detail": "entity key must be a positive int64 string",
  "instance": "/v2/process-instances/0"
}

401

No valid credential was presented.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "A valid bearer credential is required",
  "instance": "/v2/element-instances/search"
}

Headers

WWW-Authenticate

string

Allowed value: Bearer

403

The caller lacks the required permission, a tenant named in the request is not the caller’s tenant, or a cookie write has no valid CSRF token.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The principal lacks the action this route requires",
  "instance": "/v2/element-instances/search"
}

404

The entity does not exist in the caller’s tenant.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource does not exist",
  "instance": "/v2/element-instances/search"
}

413

The body exceeds the configured request-size bound.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:payload-too-large",
  "title": "Payload Too Large",
  "status": 413,
  "detail": "The request exceeds the configured size limit",
  "instance": "/v2/element-instances/search"
}

500

An internal failure. The details are never exposed.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "The request could not be completed",
  "instance": "/v2/element-instances/search"
}

501

The operation is not offered in the engine’s current deployment mode.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:mode-not-supported",
  "title": "Mode Not Supported",
  "status": 501,
  "detail": "/v2/clock is not supported in bundled mode: the deterministic virtual clock and the storage-free reset exist only for the Embedded engine; Bundled and Cluster run on the system clock over durable history, which cannot be pinned, rewound or discarded",
  "instance": "/v2/clock",
  "mode": "bundled"
}

503

Backpressure, or a dependency is not ready. Retry with the same idempotency key.

application/problem+json

An RFC 9457 problem document. type is a stable TinyConductor URN.

object

type

required

string

/^urn:bpm:error:/

title

required

string

status

required

integer

>= 400 <= 599

detail

required

string

instance

required

The request path.

string

mode

Present only on mode-not-supported. It names the engine’s mode.

string

Example

{
  "type": "urn:bpm:error:unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The required engine service is not ready",
  "instance": "/v2/element-instances/search"
}

Search element instances

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

Headers

403

Example

404

Example

413

Example

500

Example

501

Example

503

Example

Request Body^required