Status Scope

The statusScope field controls which instances are included in the search. When omitted, the default is "active".

{
  "statusScope": "active",
  "filter": { ... }
}

Values

Value	Instances included	Description
active	running, waiting, suspended	Default — non-terminal instances only
completed	completed, terminated, error	Terminal instances — historical data
all	All statuses	Full history plus active
["running", "error"]	Explicit list	Custom combination of specific statuses

Why active is the default

Active instances are a small subset of all instances. For most processes, the number of active instances at any moment is orders of magnitude smaller than the full historical record.

Defaulting to active means:

• Smaller scan: The query touches fewer rows
• Safe default: A search call without an explicit scope will not accidentally scan years of history
• Better performance: Active instances are frequently cached at the database layer

Querying historical data

Set statusScope: "completed" or statusScope: "all" when you need to query past instances:

{
  "statusScope": "completed",
  "filter": {
    "variables.applicant.documentId": "12345678900",
    "endedAt": { "$gte": "2026-01-01T00:00:00Z" }
  }
}

Cost considerations

statusScope: "all" scans both active and historical data. On deployments with large instance volumes, this is the most expensive combination. Pair it with tight filter conditions and always include a date range on startedAt or endedAt to bound the scan.

statusScope: "active" is always the fastest option. Use it for operational dashboards and real-time monitoring.