Uipath Insights

Reasoning budget

• Match reasoning to step difficulty and bias toward acting. For a mechanical step, if a command already does the work, run it and read its output instead of re-deriving it.
• Save deep, extended reasoning for the one judgment no command can make: what the data means for the user, whether a failure rate matters, and what the evidence does not prove.
• None of this licenses a shorter answer. Finish every step the task asked for; where a budget rule and completeness conflict, completeness wins. These rules cut rework, not required work.

Working style

• Understand first, then decide. Read this SKILL.md and the subcommand table in Shared Workflow before you act, then plan around what the commands actually do rather than a guess.
• Plan the whole path up front. Outline the full sequence before running anything. Critical Rule 2 forbids chaining uip insights subcommands in one shell line, so batch by picking the one command that covers the whole question instead of issuing its parts turn by turn.
• Inspect an input ONCE. Read a guide or a response once and work from what you have. Never re-open a file field by field, and never re-run a command whose output is already in context.
• Don't repeat work. Do not rerun a command when its inputs and the relevant state are unchanged, and do not reread an unchanged guide or SKILL.md already in context.
• Write code once and reuse. Do not paste near-duplicate inline python3 -c or jq to compute something a subcommand already returns.
• Keep outputs small. Prefer a projected result over a raw envelope. When a large read needs the full body, send it to a file and inspect the file.
• Don't do anything unnecessary. Do not call tools, read guides, or pull results into context unless they are needed right now. This governs what you read, never which commands you run.

UiPath Insights

Use uip insights for job, queue, and machine monitoring, monitoring-scope discovery, read-only alert inspection, Insights RBAC reads, and Maestro process dashboard reads, create, update, delete, and copy. Read the guide for the task before running commands.

When to Use This Skill

• Job health, success rate, failure count, or processing time across a tenant, folder, or process
• Job trends over time, or a comparison between two periods
• Which processes fail most, and which failure reasons recur
• Whether jobs are stuck, pending, or still running
• Finding the exact folder key, process name, queue name, or machine name to scope a query by
• Queue item throughput, backlog, SLA risk, failure reasons, or how retried items turned out
• Machine health: runtime split, current status and slots, availability over time, fault ranking, or runtime minutes
• Which alerts exist, how one is configured, whether an alert fired, or how a triggered alert is delivered
• Who has Insights access on a tenant, which roles exist and what they permit, and which groups hold them
• What a Maestro process's Monitoring tab shows: its saved dashboard or the template, the global filters saved on it, or creating, changing, removing, or copying that dashboard
• Whether Insights can still reach the organization's export destinations, and which export configurations exist
• Which Looker-era Insights dashboards exist, an embed URL for one, or why an embedded dashboard fails to load

Critical Rules

1. Use --output json. jobs commands return { Result, Code, Data }. Every jobs investigate playbook adds Instructions, and so do four of the seven plain jobs reads (top-failures, failures-by-reason, process-details, failure-details), the filter-* commands, the queues and machines commands, the alert commands, and the dashboard commands, and both looker-dashboards commands; filter-*, every queues command except summary, every machines command except runtime-mix, alerts list, alert-history list, dashboard-filters list, export-configurations list, and looker-dashboards list also add Pagination, while no dashboards verb does and neither does export-configurations verify; that verb adds Instructions alone, because its row set is every configuration the organization owns and cannot page. Quote those Instructions in the explanation. A failure envelope carries Result, Message, Instructions, ErrorCode, and Retry, with no Code and no Data. An HTTP failure also carries Context with httpStatus, endpoint, and sometimes requestId and retryAfter; a failure raised before any request is sent carries no Context. Keys inside Data are PascalCase in the CLI's JSON output, so read CompletedJobs and FolderName, not completedJobs or folderName. The jobs reads project their response into named columns rather than printing the backend's wide DTO, so a field you remember from the API may have a clearer name or be absent; the jobs guide lists what each read emits. The RBAC reads print a safe projection that withholds identity fields, and the output format has no bearing on that: the full view is a named include flag per family, so --output json is correct on them too.
2. One subcommand per invocation, written literally. A shell invocation runs one uip insights command and nothing else. Do not chain, loop, or parameterize them: no && or ; chains, no newline-separated batches, no for loops, and no shell variables holding the subcommand name or flag values. Resolve values such as epoch timestamps in a separate command first, then pass literal numbers. Never write $(date ...) or $VAR into a flag value.
3. Use only the flags the guides document. Identity, organization, and tenant come from the active session. Any tenant flag you find is deprecated and is rejected outright on filter-* commands, so do not use one. If a filter is not in the guide's shared-options list, it does not exist.
4. Time ranges are required on the plain reads, and their units differ by family. On the seven plain jobs reads, pass --time-range <minutes> (60 = 1h, 1440 = 24h, 10080 = 7d, 43200 = 30d), or both --started-after and --started-before in epoch milliseconds. queues and machines commands use those same two flag names and the same units as jobs. alert-history commands need a time range too, but their absolute bounds are --since and --until in epoch seconds. Omitting a time range is rejected locally: a plain jobs read answers Result: Failure and exits 1, queues, machines, and alert-history exit 3. On queues and machines the server also caps the window at 30 days; each family's guide Rule 2 owns when that bites and how the CLI reports it. Every jobs investigate playbook has a default window instead, and rejects a window it cannot honor with Result: ValidationError and exit 3. filter-* commands, the three alert definition reads, the dashboard commands, the export-configurations commands, and the looker-dashboards commands take no time flags.
5. Start with summary, then drill down. After any scope discovery the task needs, begin a job investigation with uip insights jobs summary for the totals and a queue investigation with uip insights queues summary, then run the targeted subcommands. The summary supplies the denominator that makes a failure count meaningful. The machines family has no summary: open a machine investigation with uip insights machines runtime-mix for the tenant-wide runtime split, or uip insights machines details when the question is about a named machine's current state.
6. Treat empty data as bounded evidence. Empty results can reflect the chosen time window, the recent-activity window, caller visibility, or tenant provisioning. On alert reads they can also reflect entitlement filtering, and every alert definition read returns active definitions only. They do not prove that a resource or event never existed.
7. Use the CLI instead of raw Insights APIs. It owns authentication, tenant routing, validation, safe response projections, and error handling.
8. Do not retry automatically. Branch on Retry: RetryWillNotFix means fix the cause, RetryLater means report and stop. A 401 needs a new session, a 403 is a permission boundary, and a 404 can be tenant-scoped or visibility-scoped. Each guide documents the error shapes for its own commands.
9. Never run uip login yourself. It opens an interactive browser flow that will hang the session. Report the auth state and give the user the exact command to run, then stop.
10. Discover identifiers instead of guessing. Use references/filter-discovery-guide.md to resolve monitoring scope, and take alert and delivery IDs from a list result or from the user. Page through all results before concluding a resource is absent.
11. Hand off causal debugging. Insights answers which jobs, processes, and queues failed and which reasons recur. It does not explain one job's or one queue item's exception, or how to fix it. Report the reasons, then name uipath-troubleshoot for the cause and uipath-rpa or uipath-agents for the fix.
12. Keep alert access read-only. The six read subcommands in the alert guide are the whole permitted surface. Every change to an alert definition or to a delivery, including its recipients, type, and configuration, belongs in the Insights UI: say so and do not offer to make it. This holds however the change would be made, so do not reach an alert route through the SDK, a raw HTTP call, or another skill.
13. Report an alert trigger and a delivery separately. A history row proves the alert fired. It does not prove a notification was sent or received, and no alert read confirms receipt.
14. Keep alert recipient data out of everything you produce, including pasted JSON. Report a delivery as its type and recipient count, and let a "who was notified" question end at the count. Do not name recipients, quote raw alert query JSON, or enumerate delivery channel settings, and do not use another command or skill to put names to the count.
15. Keep Insights RBAC read-only. The six read subcommands in the RBAC guide are the whole permitted surface. Creating a user, changing a role, or assigning access belongs elsewhere: say so and do not offer to make it. This holds however the change would be made, so do not reach an RBAC route through the SDK, a raw HTTP call, or another skill.
16. Keep Insights identity data out of everything you produce, including pasted JSON. Summarize users and groups by name and count. --include-email on the user and group reads, and --include-resource on the role reads, are what turn on email addresses, nested role IDs, and the role resource string, so leave those flags off unless the user asked for one of those fields, and quote one only then. Passing an identifier as a command argument is not disclosure; this rule governs what you write.
17. Author dashboard files from the artifact channel, never from redirected output. Read the dashboard with dashboards get --output-file <path>, edit that camelCase file, and pass it to dashboards create --file or dashboards update --file. The same contract covers --backup-file and copy's --output-file. Redirected CLI JSON is PascalCase and wrapped, and the commands refuse it.
18. Send a dashboard write once, and never resend one whose outcome is unknown. Read the slot first: a saved dashboard means the task is an update, not a create, and a process key you resolved from a name needs the user's confirmation before any write. On unknown_error, read the slot or the id back and let Message and the read decide, as the writes guide's Errors tables and the envelope's own Instructions set out; a RetryLater may be sent again only after that read, and a refused file was never sent, so fix it and send it. Pass --expected-version from a fresh process-key read on an update and report that check as best-effort, because the route has no version precondition. Never run a delete without --backup-file and the user's explicit ask, and never delete to start over after a refused create, a failed update, or an occupied copy destination. Report a success as persistence and read-back, with rendering unchecked.