Search past decision evaluations

POST

/v2/decision-instances/search

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("http://localhost:8080/v2/decision-instances/search"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{ \"filter\": { \"decisionDefinitionId\": \"shipping_fee\", \"evaluationDate\": { \"$gte\": \"2026-09-01T00:00:00Z\", \"$lt\": \"2026-10-01T00:00:00Z\" } }, \"sort\": [ { \"field\": \"evaluationDate\", \"order\": \"DESC\" } ], \"page\": { \"limit\": 50 } }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const url = 'http://localhost:8080/v2/decision-instances/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"filter":{"decisionDefinitionId":"shipping_fee","evaluationDate":{"$gte":"2026-09-01T00:00:00Z","$lt":"2026-10-01T00:00:00Z"}},"sort":[{"field":"evaluationDate","order":"DESC"}],"page":{"limit":50}}'
};

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/decision-instances/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "filter": { "decisionDefinitionId": "shipping_fee", "evaluationDate": { "$gte": "2026-09-01T00:00:00Z", "$lt": "2026-10-01T00:00:00Z" } }, "sort": [ { "field": "evaluationDate", "order": "DESC" } ], "page": { "limit": 50 } }'

Available inEmbeddedBundledCluster

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

Lists the decisions the caller’s tenant evaluated, one item per decision of each evaluation: a business rule task’s (with its process instance and element instance) or an evaluation through the API (no instance). An evaluation of a decision that requires others lists those first; decisionEvaluationInstanceKey is <decisionEvaluationKey>-<position>, from 1. A failed evaluation marks the decision it failed on FAILED, with evaluationFailure.

Newest first by default. Every filter takes a plain value or an object of operators (evaluationDate takes $gt … $lte for a date range); sort by any 8.9 sort field; page with page.after or page.from. totalItems counts at most 10,000 matches, and hasMoreTotalItems says when there are more. The state filter takes EVALUATED and FAILED; UNSPECIFIED and UNKNOWN match nothing. A caller whose grants name some decisions sees only those. Evaluations age out with their tenant’s history retention: a task’s with its process instance, one through the API on its own.

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

application/json

object

filter

object

decisionEvaluationInstanceKey

Any of:

string

state

Any of:

string

evaluationFailure

Any of:

string

evaluationDate

Any of:

string

decisionDefinitionId

Any of:

string

decisionDefinitionName

Any of:

string

decisionDefinitionVersion

Any of:

string

decisionDefinitionType

Any of:

string

decisionEvaluationKey

Any of:

string

processDefinitionKey

Any of:

string

processInstanceKey

Any of:

string

businessId

Any of:

string

decisionDefinitionKey

Any of:

string

elementInstanceKey

Any of:

string

rootDecisionDefinitionKey

Any of:

string

decisionRequirementsKey

Any of:

string

tenantId

Any of:

string

sort

Sorted by these properties in turn, then newest first; a missing value sorts last.

Array<object>

object

field

required

string

Allowed values: businessId decisionDefinitionId decisionDefinitionKey decisionDefinitionName decisionDefinitionType decisionDefinitionVersion decisionEvaluationInstanceKey decisionEvaluationKey elementInstanceKey evaluationDate evaluationFailure processDefinitionKey processInstanceKey rootDecisionDefinitionKey state 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": {
    "decisionDefinitionId": "shipping_fee",
    "evaluationDate": {
      "$gte": "2026-09-01T00:00:00Z",
      "$lt": "2026-10-01T00:00:00Z"
    }
  },
  "sort": [
    {
      "field": "evaluationDate",
      "order": "DESC"
    }
  ],
  "page": {
    "limit": 50
  }
}

Responses

200

One page of decision instances.

application/json

object

items

required

Array<object>

object

businessId

required

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

null

decisionDefinitionId

required

string

decisionDefinitionKey

required

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

string

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

decisionDefinitionName

required

The decision’s name; empty when the model gives none.

string

decisionDefinitionType

required

string

Allowed values: DECISION_TABLE LITERAL_EXPRESSION UNKNOWN

decisionDefinitionVersion

required

The decision’s version; -1 for a required decision that failed before the evaluation described it.

integer format: int32

decisionEvaluationInstanceKey

required

string

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

decisionEvaluationKey

required

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

string

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

elementInstanceKey

required

Any of:

string
null

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

string

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

evaluationDate

required

An RFC 3339 timestamp.

string format: date-time

evaluationFailure

required

Why the evaluation failed

string | null

processDefinitionKey

required

Any of:

string
null

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

string

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

processInstanceKey

required

Any of:

string
null

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

string

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

result

required

The decision’s output as JSON text (null for a decision that failed).

string

rootDecisionDefinitionKey

required

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

string

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

rootProcessInstanceKey

required

Any of:

string
null

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

string

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

state

required

string

Allowed values: EVALUATED FAILED

tenantId

required

string

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": [
    {
      "decisionDefinitionKey": "2251799813685249",
      "decisionDefinitionType": "DECISION_TABLE",
      "decisionEvaluationKey": "2251799813685249",
      "elementInstanceKey": "2251799813685249",
      "processDefinitionKey": "2251799813685249",
      "processInstanceKey": "2251799813685249",
      "rootDecisionDefinitionKey": "2251799813685249",
      "rootProcessInstanceKey": "2251799813685249",
      "state": "EVALUATED"
    }
  ]
}

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/decision-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/decision-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/decision-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/decision-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/decision-instances/search"
}