Agent

Service for retrieving UiPath Agent trace metrics.

Methods

getErrorsTimeline()

getErrorsTimeline(options?: AgentTraceGetErrorsTimelineOptions): Promise<AgentTraceGetErrorsTimelineResponse[]>

Retrieves a trace-level time-series of error counts grouped by error name.

Parameters

Parameter	Type	Description
options?	AgentTraceGetErrorsTimelineOptions	Optional window and filters

Returns

Promise<AgentTraceGetErrorsTimelineResponse[]>

Promise resolving to an array of AgentTraceGetErrorsTimelineResponse

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Get the errors timeline
const result = await trace.getErrorsTimeline();
result.forEach((point) => {
  console.log(`${point.date} ${point.name}: ${point.value} errors`);
});

import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';

// Get the errors timeline for an agent version within a time window
const filtered = await trace.getErrorsTimeline({
  startTime: new Date('2025-05-01T00:00:00Z'),
  endTime: new Date('2025-06-01T00:00:00Z'),
  agentId: '<agentId>',
  agentVersion: '1.0.0',
  executionType: AgentTraceExecutionType.Runtime,
});

---

getGovernanceDecisions()

getGovernanceDecisions<T>(startTime: Date, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentGovernanceDecisionGetResponse> : NonPaginatedResponse<AgentGovernanceDecisionGetResponse>>

Lists individual governance decisions from agent execution traces — each policy check's allow/deny outcome with its agent, policy, pack, hook, and mode, plus the trace it belongs to — over the requested window. Filterable and paginated.

Type Parameters

Type Parameter	Default type
T extends AgentGovernanceDecisionsOptions	AgentGovernanceDecisionsOptions

Parameters

Parameter	Type	Description
startTime	Date	Inclusive lower bound for the query window
options?	T	Optional window end, filters, and pagination

Returns

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentGovernanceDecisionGetResponse> : NonPaginatedResponse<AgentGovernanceDecisionGetResponse>>

Promise resolving to a paginated or non-paginated list of AgentGovernanceDecisionGetResponse

Remarks

Requires the caller to be an organization admin. Non-admin callers get a 403 and the SDK throws an AuthorizationError.

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Decision rows since a start time
const result = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
result.items.forEach((row) => {
  console.log(`${row.hook} ${row.policyId}: ${row.evaluatorResult}`);
});

// Violations only, for one agent, paginated
const page = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), {
  endTime: new Date('2025-06-01T00:00:00Z'),
  violationsOnly: true,
  agentId: '<agentProjectKey>',
  pageSize: 25,
});
if (page.hasNextPage && page.nextCursor) {
  const next = await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'), { cursor: page.nextCursor });
}

import { isAuthorizationError } from '@uipath/uipath-typescript/core';

// Non-admin callers get a 403
try {
  await trace.getGovernanceDecisions(new Date('2025-05-01T00:00:00Z'));
} catch (error) {
  if (isAuthorizationError(error)) {
    console.error('Governance data requires an organization admin.');
  }
}

---

getGovernanceSummary()

getGovernanceSummary(startTime: Date, options?: AgentGovernanceSummaryOptions): Promise<AgentGovernanceGetSummaryResponse>

Summarizes governance decisions across agent execution traces — total decisions and violations, plus top breakdowns by hook, agent, policy, and pack — over the requested window. Filterable.

Parameters

Parameter	Type	Description
startTime	Date	Inclusive lower bound for the query window
options?	AgentGovernanceSummaryOptions	Optional window end, top-N, pack scope, and sections

Returns

Promise<AgentGovernanceGetSummaryResponse>

Promise resolving to AgentGovernanceGetSummaryResponse

Remarks

Requires the caller to be an organization admin. Non-admin callers get a 403 and the SDK throws an AuthorizationError.

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Default posture since a start time
const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
console.log(`${summary.violations} / ${summary.total} violations`);
summary.byPolicy.forEach((p) => console.log(`${p.key}: ${p.violationCount}`));

import { AgentGovernanceSection } from '@uipath/uipath-typescript/traces';

// Top 5 per breakdown, scoped to a pack, including the opt-in action/mode sections
const summary = await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'), {
  topN: 5,
  packName: 'ISO/IEC 42001:2023 Runtime',
  sections: [AgentGovernanceSection.Action, AgentGovernanceSection.Mode],
});

import { isAuthorizationError } from '@uipath/uipath-typescript/core';

// Non-admin callers get a 403
try {
  await trace.getGovernanceSummary(new Date('2025-05-01T00:00:00Z'));
} catch (error) {
  if (isAuthorizationError(error)) {
    console.error('Governance data requires an organization admin.');
  }
}

---

getLatencyTimeline()

getLatencyTimeline(options?: AgentTraceGetLatencyTimelineOptions): Promise<AgentTraceGetLatencyTimelineResponse[]>

Retrieves a trace-level time-series of latency.

Parameters

Parameter	Type	Description
options?	AgentTraceGetLatencyTimelineOptions	Optional window and filters

Returns

Promise<AgentTraceGetLatencyTimelineResponse[]>

Promise resolving to an array of AgentTraceGetLatencyTimelineResponse

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Get the latency timeline
const result = await trace.getLatencyTimeline();
result.forEach((point) => {
  console.log(`${point.date} ${point.name}: ${point.value}s`);
});

import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';

// Get the latency timeline for an agent version within a time window
const filtered = await trace.getLatencyTimeline({
  startTime: new Date('2025-05-01T00:00:00Z'),
  endTime: new Date('2025-06-01T00:00:00Z'),
  agentId: '<agentId>',
  agentVersion: '1.0.0',
  executionType: AgentTraceExecutionType.Runtime,
});

---

getSpansByReference()

getSpansByReference<T>(referenceId: string, options?: T): Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>

Retrieves spans whose reference hierarchy contains the given reference id.

Type Parameters

Type Parameter	Default type
T extends AgentTraceGetSpansByReferenceOptions	AgentTraceGetSpansByReferenceOptions

Parameters

Parameter	Type	Description
referenceId	string	Reference id matched against each span's reference hierarchy
options?	T	Optional pagination and hierarchy/time filters

Returns

Promise<T extends HasPaginationOptions<T> ? PaginatedResponse<AgentSpanGetResponse> : NonPaginatedResponse<AgentSpanGetResponse>>

Promise resolving to a paginated or non-paginated list of AgentSpanGetResponse

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Get spans by referenceId
const result = await trace.getSpansByReference('<referenceId>');
result.items.forEach((span) => console.log(span.name));

import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';

// Get spans by referenceId within a trace and time window
const page = await trace.getSpansByReference('<referenceId>', {
  traceId: '<traceId>',
  executionType: AgentTraceExecutionType.Runtime,
  startTime: new Date('2025-05-01T00:00:00Z'),
  endTime: new Date('2025-06-01T00:00:00Z'),
  pageSize: 25,
});

if (page.hasNextPage && page.nextCursor) {
  const next = await trace.getSpansByReference('<referenceId>', { cursor: page.nextCursor });
}

---

getSpansByTraceId()

getSpansByTraceId(traceId: string): Promise<AgentSpanGetResponse[]>

Retrieves every span belonging to a single trace.

Parameters

Parameter	Type	Description
traceId	string	Identifier of the trace whose spans should be returned

Returns

Promise<AgentSpanGetResponse[]>

Promise resolving to an array of AgentSpanGetResponse

Example

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

const spans = await trace.getSpansByTraceId('<traceId>');
spans.forEach((span) => {
  console.log(`${span.name} (${span.startTime} → ${span.endTime ?? 'in progress'})`);
});

---

getUnitConsumption()

getUnitConsumption(options?: AgentTraceGetUnitConsumptionOptions): Promise<AgentTraceGetUnitConsumptionResponse[]>

Retrieves trace-level per-agent unit consumption totals.

Parameters

Parameter	Type	Description
options?	AgentTraceGetUnitConsumptionOptions	Optional window and filters

Returns

Promise<AgentTraceGetUnitConsumptionResponse[]>

Promise resolving to an array of AgentTraceGetUnitConsumptionResponse

Examples

import { AgentTraces } from '@uipath/uipath-typescript/traces';

const trace = new AgentTraces(sdk);

// Get per-agent unit consumption
const result = await trace.getUnitConsumption();
result.forEach((row) => {
  console.log(`${row.agentId}: ${row.agentUnitsConsumed} Agent Units, ${row.platformUnitsConsumed} Platform Units`);
});

import { AgentTraceExecutionType } from '@uipath/uipath-typescript/traces';

// Get per-agent unit consumption for an agent version within a time window
const filtered = await trace.getUnitConsumption({
  startTime: new Date('2025-05-01T00:00:00Z'),
  endTime: new Date('2025-06-01T00:00:00Z'),
  agentId: '<agentId>',
  agentVersion: '1.0.0',
  executionType: AgentTraceExecutionType.Runtime,
});