Skip to main content

Recipe: Operational Dashboard

This recipe shows how to build a backend query that powers a real-time dashboard of active process instances — useful for support tooling, ops monitoring, or internal admin panels.

Goal​

Find all active loan-application instances that are stuck in in_review for more than 2 days and have an amount above 50,000.

Query​

POST /v1/instances/search

{
  "definitionKey": "loan-application",
  "statusScope": "active",
  "filter": {
    "variables.loan_status": "in_review",
    "variables.amount": { "$gte": 50000 },
    "startedAt": { "$lte": "2026-06-21T00:00:00Z" }
  },
  "sort": { "startedAt": 1 },
  "projection": {
    "variables.loan_status": 1,
    "variables.amount": 1,
    "variables.applicant.fullName": 1,
    "startedAt": 1,
    "correlationId": 1
  },
  "page": { "limit": 50 }
}

Set startedAt.$lte to Date.now() - 2 * 24 * 60 * 60 * 1000 (in ISO format) dynamically in your backend.

Response​

{
  "results": [
    {
      "instanceId": "inst_abc123",
      "definitionKey": "loan-application",
      "status": "waiting",
      "startedAt": "2026-06-19T10:00:00Z",
      "correlationId": "loan-2026-0042",
      "variables": {
        "loan_status": "in_review",
        "amount": 75000,
        "applicant": { "fullName": "Maria Silva" }
      }
    }
  ],
  "nextCursor": "eyJ...",
  "stats": {
    "returned": 12,
    "limit": 50,
    "scanMode": "Index Scan"
  }
}

stats.scanMode: "Index Scan" confirms the query is using an index and will perform well as the dataset grows.

Refresh pattern​

Poll this endpoint every 30–60 seconds for a live-updating dashboard. Results are strongly consistent — no caching layer, no lag between engine state and search results.

Including error instances​

To show both stuck waiting instances and error instances together:

{
  "definitionKey": "loan-application",
  "statusScope": ["waiting", "error"],
  "filter": {
    "variables.amount": { "$gte": 50000 }
  },
  "sort": { "startedAt": 1 }
}