| title | c8volt get process-instance |
|---|---|
| nav_exclude | true |
[CLI Reference]({{ "/cli/" | relative_url }})
List or fetch process instances
Get process instances by key or search criteria.
Use a known key or search by process definition, tenant, state, incidents, variables, jobs, user tasks, and time ranges. Missing explicit keys return not-found.
On Camunda 8.10, JSON includes suspendedDate in UTC when the current instance response provides a nonzero timestamp. Missing timestamps are omitted on each read; this field does not represent suspension history. Human rows and keys-only output remain unchanged.
--batch-size controls each discovery request; --limit caps instances across all pages; --total counts matching instances. Empty searches suppress the human summary under --quiet; explicit JSON and keys-only output keep their existing contracts.
--tenant limits search and selector discovery. Explicit --key and stdin keys use backend authorization without tenant filtering. A --bpmn-process-id selector must match a visible process definition before discovery.
Use --with-incidents for direct incidents, --with-vars for process-instance-scope variables, or --with-elements for runtime element instances. Add --with-listeners to --with-elements for runtime listener jobs. Listener rows use s: for job creation (not worker execution start), e: for job end, and d: for an available deadline only while the state is exactly ACTIVATED; missing times are omitted. Listener dur: measures time from job creation to its recorded end, or elapsed time for a pending job; it includes worker waiting time and is omitted when timestamps are unavailable or invalid.
Use variable-search flags to narrow list/search results natively. --var-exists requires every listed variable name to exist. --var accepts name=value equality shorthand plus advanced name.$operator=value clauses for $eq, $neq, $exists, $in, $notIn, and $like; $notin is accepted as $notIn. --var-like uses native wildcard patterns: * matches zero or more characters, ? matches one character, and escaped wildcards remain literal. Commas inside quoted values and JSON arrays stay inside the variable clause. Variable scopeKey means the scope where the variable is directly defined.
Use --has-user-tasks to fetch process instances by their owning user-task keys.
c8volt get process-instance [flags]
./c8volt get process-instance --bpmn-process-id <bpmn-process-id> --state active --limit 5
./c8volt get process-instance --key <process-instance-key>
./c8volt get process-instance --state suspended --json
./c8volt get process-instance --state active --total
./c8volt get process-instance --has-user-tasks <user-task-key>
./c8volt get process-instance --incidents-only --with-incidents --limit 5
./c8volt get process-instance --direct-incidents-only --incident-error-type io_mapping_error --incident-error-message intentional --limit 5
./c8volt get process-instance --var-exists payload,email --limit 5
./c8volt get process-instance --var 'status="approved"' --limit 5
./c8volt get process-instance --var 'status.$in=["approved","pending"]' --limit 5
./c8volt get process-instance --var-like 'email=*@example.com,customerId=CUST-????' --limit 5
./c8volt get process-instance --state active --with-vars --var-value-limit 120 --limit 5
./c8volt get process-instance --key <process-instance-key> --with-incidents
./c8volt get process-instance --key <process-instance-key> --with-vars
./c8volt get process-instance --key <process-instance-key> --with-vars --var-value-limit 120
./c8volt get process-instance --key <process-instance-key> --with-elements
./c8volt get process-instance --key <process-instance-key> --with-elements --with-listeners
./c8volt get process-instance --start-date-after 2026-05-01 --start-date-before 2026-05-31 --limit 5
./c8volt get process-instance --key <process-instance-key> --key <another-process-instance-key>
-n, --batch-size int32 number of process instances to request per page; does not cap total results (max limit 1000 enforced by server) (default 1000)
-b, --bpmn-process-id string BPMN process ID to filter process instances
--children-only show only child process instances
--direct-incidents-only show only process instances with direct incident details
--end-date-after string only include process instances with end date >= YYYY-MM-DD
--end-date-before string only include process instances with end date <= YYYY-MM-DD
--end-date-newer-days int only include process instances with end date N days old or newer (0 means today) (default -1)
--end-date-older-days int only include process instances with end date N days old or older (default -1)
--fail-fast stop scheduling new instances after the first error
--has-user-tasks strings user task key(s) whose owning process instances should be fetched
-h, --help help for process-instance
--incident-error-message string case-insensitive incident error message substring filter for keyed --with-incidents or list/search --direct-incidents-only
--incident-error-type string case-insensitive incident error type filter for keyed --with-incidents or list/search --direct-incidents-only
--incident-message-limit int maximum characters to show for incident messages when --with-incidents is set; 0 disables truncation
--incident-state string incident state scope for keyed --with-incidents: active, pending, resolved, migrated, unknown, all (default "active")
--incidents-only show only process instances that have incidents
-k, --key strings process instance key(s) to fetch
-l, --limit int32 maximum number of matching process instances to return across all pages; omit to continue through all matches
--no-incidents-only show only process instances that have no incidents
--no-worker-limit use all queued jobs as workers when --workers is unset
--orphan-children-only show only child instances with missing parents
--parent-key string parent process instance key to filter process instances
--pd-key string process definition key (mutually exclusive with bpmn-process-id, pd-version, and pd-version-tag)
--pd-version int32 process definition version
--pd-version-tag string process definition version tag
--roots-only show only root process instances
--start-date-after string only include process instances with start date >= YYYY-MM-DD
--start-date-before string only include process instances with start date <= YYYY-MM-DD
--start-date-newer-days int only include process instances N days old or newer (0 means today) (default -1)
--start-date-older-days int only include process instances N days old or older (default -1)
-s, --state string state to filter process instances: all, active, suspended (Camunda 8.10), completed, canceled, terminated (default "all")
--total return only the numeric total of matching process instances; capped backend totals are counted by paging
--var stringArray require variable equality or advanced clause(s); repeat or separate clauses with commas
--var-exists stringArray require variable name(s) to exist; repeat or separate names with commas
--var-like stringArray require variable value pattern clause(s); repeat or separate clauses with commas
--var-value-limit int maximum characters to show for variable values when --with-vars is set; 0 disables truncation
--with-elements include runtime element instances for keyed or list/search process-instance output
--with-incidents include direct incident keys, states, and messages for keyed or list/search process-instance output
--with-listeners include runtime listener jobs; requires --with-elements
--with-vars include process-instance-scope variables for keyed or list/search process-instance output
-w, --workers int maximum concurrent workers when --batch-size > 1 (default: min(batch-size, 2*GOMAXPROCS, 32))
--all-tenants clear configured tenant filtering and search all tenants visible to the authenticated user; mutually exclusive with --tenant
-y, --auto-confirm auto-confirm prompts for non-interactive use
--automation enable non-interactive mode for commands that explicitly support it
--config string path to config file
--debug enable debug logging
-j, --json output as JSON (where applicable)
--keys-only output keys only (where applicable)
--log-level string log level (debug, info, warn, error) (default "info")
--no-indicator disable transient terminal activity indicators
--profile string config active profile name to use (e.g. dev, prod)
-q, --quiet suppress output except errors
--request-rate float maximum shared request starts per second (fractions allowed; 0 disables pacing)
--tenant string tenant ID for discovery/search, selection, create, deploy, and run flows; explicit empty values can clear configured discovery filters, and explicit keys/IDs remain backend-authorized
--timeout duration HTTP request timeout (default 30s)
-v, --verbose show additional output
- [c8volt get]({{ "/cli/c8volt_get" | relative_url }}) - Inspect cluster, process, job, element, incident, tenant, and resource state