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,
});

---

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.

Returns a PaginatedResponse when pagination options (pageSize, cursor, or jumpToPage) are provided, otherwise a NonPaginatedResponse.

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} AGU, ${row.platformUnitsConsumed} PLTU`);
});

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,
});