Traces

Service for querying UiPath execution traces (spans).

Traces are OpenTelemetry-compatible execution records generated by agents, robots, Maestro processes, conversational agents, and other UiPath execution sources. The source field on each SpanGetResponse identifies the originating platform.

Example

import { UiPath } from '@uipath/uipath-typescript/core';
import { Traces } from '@uipath/uipath-typescript/traces';

const sdk = new UiPath(config);
await sdk.initialize();

const traces = new Traces(sdk);
const spans = await traces.getById('<traceId>');

Methods

getById()

getById(traceId: string, options?: TracesGetByIdOptions): Promise<SpanGetResponse[]>

Gets all spans for a specific trace ID.

Returns up to pageSize spans (default 1000) in a single fetch. Accepts both GUID format and OTEL 32-char hex format — the API normalizes both.

Parameters

Parameter	Type	Description
traceId	string	Trace identifier
options?	TracesGetByIdOptions	Optional filters TracesGetByIdOptions

Returns

Promise<SpanGetResponse[]>

Promise resolving to an array of SpanGetResponse, each containing span identity, timing, status, source platform, attributes, verbosity, execution type, lineage context, and any file attachments.

Examples

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

const traces = new Traces(sdk);
const spans = await traces.getById('<traceId>');
console.log(spans.length, spans[0].spanType, spans[0].status);

// Filter to a specific agent's spans
const agentSpans = await traces.getById('<traceId>', {
  agentId: '<agentId>',
  pageSize: 500,
});

---

getSpansByIds()

getSpansByIds(traceId: string, spanIds: string[]): Promise<SpanGetResponse[]>

Gets specific spans by trace ID and span IDs.

Accepts OTEL 16-char hex or GUID format for span IDs.

Parameters

Parameter	Type	Description
traceId	string	Trace identifier
spanIds	string[]	List of span IDs to retrieve

Returns

Promise<SpanGetResponse[]>

Promise resolving to an array of matching SpanGetResponse, each containing span identity, timing, status, source platform, attributes, verbosity, execution type, lineage context, and any file attachments.

Example

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

const traces = new Traces(sdk);

// First retrieve all spans to find the IDs you want
const allSpans = await traces.getById('<traceId>');
const spanIds = allSpans.slice(0, 3).map(s => s.id);

const subset = await traces.getSpansByIds('<traceId>', spanIds);