Class: WeaveClient

TypeScript SDK reference

weave / WeaveClient

Table of contents

Constructors

• constructor

Properties

• projectId
• settings
• traceServerApi

Methods

• addScore
• createCall
• finishCall
• finishCallWithException
• get
• getAgentCustomAttributes
• getAgentSpanStats
• getAgentSpans
• getAgentTurn
• getAgentTurns
• getAgentVersions
• getAgents
• getCall
• getCallStack
• getCalls
• getCallsIterator
• getCurrentAttributes
• linkPromptToRegistry
• publish
• pushNewCall
• runWithAttributes
• runWithCallStack
• saveCallEnd
• saveCallStart
• saveOp
• searchAgents
• serializeAudio
• updateCall
• waitForBatchProcessing

Constructors

constructor

• new WeaveClient(«destructured»): WeaveClient

Parameters

Name	Type
«destructured»	Object
› projectId	string
› settings?	Partial<Settings>
› traceServerApi	Api<any>

Returns

WeaveClient

Defined in

src/weaveClient.ts:459

Properties

projectId

• projectId: string

Defined in

src/weaveClient.ts:456

---

settings

• settings: Settings

Defined in

src/weaveClient.ts:457

---

traceServerApi

• traceServerApi: Api<any>

Defined in

src/weaveClient.ts:455

Methods

addScore

▸ addScore(predictCallId, scorerCallId, runnableRefUri, scorerOutput): Promise<string>

Add a scorer result (e.g., scorer output) to a call. Used in imperative evaluation to attach scorer results to predict calls.

Parameters

Name	Type	Description
predictCallId	string	ID of the predict call to attach feedback to
scorerCallId	string	ID of the scorer call that generated the feedback
runnableRefUri	string	URI of the scorer (Op or Object ref)
scorerOutput	any	Output of the scorer

Returns

Promise<string>

Defined in

src/weaveClient.ts:1727

---

createCall

▸ createCall(internalCall, opRef, params, parameterNames, thisArg, currentCall, parentCall, startTime, displayName?, attributes?): Promise<void>

Parameters

Name	Type
internalCall	InternalCall
opRef	any
params	any[]
parameterNames	ParameterNamesOption
thisArg	any
currentCall	CallStackEntry
parentCall	undefined | CallStackEntry
startTime	Date
displayName?	string
attributes?	Record<string, any>

Returns

Promise<void>

Defined in

src/weaveClient.ts:1570

---

finishCall

▸ finishCall(call, result, currentCall, parentCall, summarize, endTime, startCallPromise): Promise<void>

Parameters

Name	Type
call	InternalCall
result	any
currentCall	CallStackEntry
parentCall	undefined | CallStackEntry
summarize	undefined | (result: any) => Record<string, any>
endTime	Date
startCallPromise	Promise<void>

Returns

Promise<void>

Defined in

src/weaveClient.ts:1630

---

finishCallWithException

▸ finishCallWithException(call, error, currentCall, parentCall, endTime, startCallPromise): Promise<void>

Parameters

Name	Type
call	InternalCall
error	any
currentCall	CallStackEntry
parentCall	undefined | CallStackEntry
endTime	Date
startCallPromise	Promise<void>

Returns

Promise<void>

Defined in

src/weaveClient.ts:1672

---

get

▸ get(ref): Promise<any>

Parameters

Name	Type
ref	ObjectRef

Returns

Promise<any>

Defined in

src/weaveClient.ts:1025

---

getAgentCustomAttributes

▸ getAgentCustomAttributes(options): Promise<Response<GetAgentCustomAttributesResult>>

Discover typed custom-attribute keys observed on agent spans in the project. Each result row is one (source, key, value_type) triple plus a count of how many spans carry it, which is what the spans query/group/stats APIs use to reference custom attrs.

Filter the spans considered by passing query (a structured span filter), startedAfter / startedBefore (ISO-8601), or both. Use limit / offset to page through the discovered keys.

Parameters

Name	Type
options	GetAgentCustomAttributesOptions

Returns

Promise<Response<GetAgentCustomAttributesResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentCustomAttributes({
  query: {
    $expr: {
      $eq: [{$getField: 'agent_name'}, {$literal: 'my-agent'}],
    },
  },
  startedAfter: '2026-06-15T00:00:00Z',
  limit: 200,
});

for (const attr of resp.data.attributes ?? []) {
  console.log(`${attr.source}.${attr.key} (${attr.value_type}): ${attr.span_count}`);
}

Defined in

src/weaveClient.ts:772

---

getAgentSpanStats

▸ getAgentSpanStats(options): Promise<Response<GetAgentSpanStatsResult>>

Agregations over agent spans in the project, returned as rows + column metadata suitable for time-series / bucketed visualizations.

start (required) and end define the time window. Each entry in metrics declares a field to extract and how to aggregate it (sum, avg, count, percentiles, etc.). Pass granularity (seconds) to bucket rows by time, or groupBy to break results out per agent / provider / model / etc. query filters the underlying spans before aggregation.

Parameters

Name	Type
options	GetAgentSpanStatsOptions

Returns

Promise<Response<GetAgentSpanStatsResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentSpanStats({
  start: '2026-06-10T00:00:00Z',
  end: '2026-06-23T00:00:00Z',
  granularity: 86400, // one row per day
  metrics: [
    {
      alias: 'total_input_tokens',
      value_type: 'number',
      aggregations: ['sum'],
      value: {source: 'field', key: 'input_tokens'},
    },
  ],
  groupBy: [{key: 'agent_name'}],
});

for (const row of resp.data.rows ?? []) {
  console.log(row.started_at_bucket, row.agent_name, row.total_input_tokens);
}

Defined in

src/weaveClient.ts:621

---

getAgentSpans

▸ getAgentSpans(options): Promise<Response<GetAgentSpansResult>>

Query agent spans, optionally filtered by agent name and/or a mongo-style query expression.

Parameters

Name	Type
options	GetAgentSpansOptions

Returns

Promise<Response<GetAgentSpansResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentSpans({agentName: 'my-agent', limit: 20});

for (const span of resp.data.spans) {
  console.log(span.span_id, span.span_name, span.input_tokens);
}

Example

const client = await weave.init('entity/project');

const resp = await client.getAgentSpans({
  agentName: 'my-agent',
  query: {
    $expr: {$gt: [{$getField: 'input_tokens'}, {$literal: 1000}]},
  },
});

for (const span of resp.data.spans) {
  console.log(span.span_id, span.span_name, span.input_tokens);
}

Defined in

src/weaveClient.ts:566

---

getAgentTurn

▸ getAgentTurn(options): Promise<Response<AgentTraceChatRes>>

Get data (including messages) for a single turn (by traceId).

Parameters

Name	Type
options	GetAgentTurnOptions

Returns

Promise<Response<AgentTraceChatRes>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentTurn({
  traceId: '01997b8a-2c89-7c4d-9d0e-2f7e5b9a1b2c',
  includeFeedback: true,
});

console.log(resp.data.root_span_name, resp.data.total_duration_ms);

for (const message of resp.data.messages ?? []) {
  if (message.user_message) console.log('user:', message.user_message);
  if (message.assistant_message) console.log('assistant:', message.assistant_message);
}

Defined in

src/weaveClient.ts:655

---

getAgentTurns

▸ getAgentTurns(options): Promise<Response<GetAgentTurnsResult>>

Get data (including messages) for many turns (by conversationId).

Parameters

Name	Type
options	GetAgentTurnsOptions

Returns

Promise<Response<GetAgentTurnsResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentTurns({
  conversationId: 'trace_c50312356de3487fa90e381c9399b5b4',
  limit: 20,
  includeFeedback: true,
});

for (const turn of resp.data.turns ?? []) {
  console.log(turn.trace_id, turn.root_span_name);
  for (const message of turn.messages ?? []) {
    if (message.user_message) console.log('user:', message.user_message);
    if (message.assistant_message) console.log('assistant:', message.assistant_message);
  }
}

console.log(`total turns: ${resp.data.total_turns}, has more: ${resp.data.has_more}`);

Defined in

src/weaveClient.ts:688

---

getAgentVersions

▸ getAgentVersions(options): Promise<Response<GetAgentVersionsResult>>

List versions for a given agent.

Parameters

Name	Type
options	GetAgentVersionsOptions

Returns

Promise<Response<GetAgentVersionsResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgentVersions({agentName: 'my-agent', limit: 20});

for (const version of resp.data.versions) {
  console.log(version.agent_version, version.total_input_tokens);
}

console.log(`total count: ${resp.data.total_count}`)

Defined in

src/weaveClient.ts:522

---

getAgents

▸ getAgents(options?): Promise<Response<GetAgentsResult>>

List agents with aggregated stats.

Parameters

Name	Type
options	GetAgentsOptions

Returns

Promise<Response<GetAgentsResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.getAgents({limit: 20});

for (const agent of resp.data.agents) {
  console.log(agent.agent_name, agent.total_input_tokens);
}

console.log(`total count: ${resp.data.total_count}`)

Defined in

src/weaveClient.ts:488

---

getCall

▸ getCall(callId, includeCosts?): Promise<Call>

Parameters

Name	Type	Default value
callId	string	undefined
includeCosts	boolean	false

Returns

Promise<Call>

Defined in

src/weaveClient.ts:902

---

getCallStack

▸ getCallStack(): CallStack

Returns

CallStack

Defined in

src/weaveClient.ts:1482

---

getCalls

▸ getCalls(options?): Promise<Call[]>

Parameters

Name	Type
options?	GetCallsOptions

Returns

Promise<Call[]>

Defined in

src/weaveClient.ts:935

▸ getCalls(options?, includeCosts?, limit?): Promise<Call[]>

Parameters

Name	Type
options?	CallsFilter
includeCosts?	boolean
limit?	number

Returns

Promise<Call[]>

Defined in

src/weaveClient.ts:936

---

getCallsIterator

▸ getCallsIterator(options?, includeCosts?, limit?): AsyncIterableIterator<CallSchema, any, any>

Parameters

Name	Type
options?	CallsFilter
includeCosts?	boolean
limit?	number

Returns

AsyncIterableIterator<CallSchema, any, any>

Defined in

src/weaveClient.ts:957

▸ getCallsIterator(options?): AsyncIterableIterator<CallSchema, any, any>

Parameters

Name	Type
options?	GetCallsOptions

Returns

AsyncIterableIterator<CallSchema, any, any>

Defined in

src/weaveClient.ts:962

---

getCurrentAttributes

▸ getCurrentAttributes(): Record<string, any>

Returns

Record<string, any>

Defined in

src/weaveClient.ts:1486

---

linkPromptToRegistry

▸ linkPromptToRegistry(prompt, options): Promise<LinkAssetToRegistryRes>

Link a published prompt version into a registry portfolio.

Parameters

Name	Type
prompt	RegistryLinkable
options	LinkPromptToRegistryOptions

Returns

Promise<LinkAssetToRegistryRes>

Defined in

src/weaveClient.ts:1181

---

publish

▸ publish(obj, objId?): Promise<ObjectRef>

Parameters

Name	Type
obj	any
objId?	string

Returns

Promise<ObjectRef>

Defined in

src/weaveClient.ts:890

---

pushNewCall

▸ pushNewCall(): Object

Returns

Object

Name	Type
currentCall	CallStackEntry
newStack	CallStack
parentCall?	CallStackEntry

Defined in

src/weaveClient.ts:1490

---

runWithAttributes

▸ runWithAttributes<T>(attributes, fn): T

Type parameters

Name
T

Parameters

Name	Type
attributes	Record<string, any>
fn	() => T

Returns

T

Defined in

src/weaveClient.ts:1498

---

runWithCallStack

▸ runWithCallStack<T>(callStack, fn): T

Type parameters

Name
T

Parameters

Name	Type
callStack	CallStack
fn	() => T

Returns

T

Defined in

src/weaveClient.ts:1494

---

saveCallEnd

▸ saveCallEnd(callEnd): void

Parameters

Name	Type
callEnd	EndedCallSchemaForInsert

Returns

void

Defined in

src/weaveClient.ts:1477

---

saveCallStart

▸ saveCallStart(callStart): void

Parameters

Name	Type
callStart	StartedCallSchemaForInsert

Returns

void

Defined in

src/weaveClient.ts:1472

---

saveOp

▸ saveOp(op, objId?): Promise<OpRef>

Parameters

Name	Type
op	Op<(…args: any[]) => any>
objId?	string

Returns

Promise<OpRef>

Defined in

src/weaveClient.ts:1537

---

searchAgents

▸ searchAgents(options): Promise<Response<SearchAgentsResult>>

Full-text search across agent messages in the project. Returns hits grouped by conversation, with a preview of each matched message.

query is the full-text search term. Pass an empty string to retrieve all messages matching the structured filters (agentName, conversationId, traceId) without text matching. Use limit / offset to page through results.

Parameters

Name	Type
options	SearchAgentsOptions

Returns

Promise<Response<SearchAgentsResult>>

Example

const client = await weave.init('entity/project');
const resp = await client.searchAgents({
  query: 'Liverpool',
  agentName: 'Assistant',
  limit: 20,
});

for (const conversation of resp.data.results ?? []) {
  console.log(`${conversation.conversation_id} (${conversation.agent_name})`);
  for (const match of conversation.matched_messages) {
    console.log(`  [${match.role}] ${match.content_preview}`);
  }
}

console.log(`total conversations: ${resp.data.total_conversations}`);

Defined in

src/weaveClient.ts:730

---

serializeAudio

▸ serializeAudio(data, audioType?): Promise<SerializedFileBlob>

Upload raw audio bytes to the Weave content store and return the CustomWeaveType placeholder that can be embedded in a call output.

Use this when building call outputs manually (e.g. via saveCallEnd) where the automatic serialization pipeline from finishCall is not used.

Parameters

Name	Type	Default value	Description
data	Buffer<ArrayBufferLike>	undefined	Raw audio bytes (WAV for best browser compatibility)
audioType	"wav"	DEFAULT_AUDIO_TYPE	File format — currently only ‘wav’ is supported

Returns

Promise<SerializedFileBlob>

Defined in

src/weaveClient.ts:1424

---

updateCall

▸ updateCall(callId, displayName): Promise<void>

Parameters

Name	Type
callId	string
displayName	string

Returns

Promise<void>

Defined in

src/weaveClient.ts:1710

---

waitForBatchProcessing

▸ waitForBatchProcessing(): Promise<void>

Returns

Promise<void>

Defined in

src/weaveClient.ts:801