WeaveClient - Weights & Biases Documentation

Defined in: src/weaveClient.ts:519

Properties

projectId

projectId: string

Defined in: src/weaveClient.ts:538

settings

settings: object

Defined in: src/weaveClient.ts:539

attributes

readonly attributes: Record<string, any>

A map of attributes applied to every trace produced by this client.

genai

readonly genai: object

genai.batchOptions

optional batchOptions: BufferConfig

BatchSpanProcessor configuration. Ignored unless spanProcessor === 'batch'.

genai.spanProcessor

optional spanProcessor: "batch" | "simple" | SpanProcessor

How GenAI spans are exported.

'batch' (default): BatchSpanProcessor, suitable for production agents and long-lived processes.
'simple': SimpleSpanProcessor, one HTTP POST per span. Useful for tests and short-lived CLIs where deterministic flush matters more than throughput.
SpanProcessor instance: a user-supplied processor. The caller owns its lifecycle; the Weave OTLP exporter targeting /agents/otel/v1/traces is not used.

printCallLink

readonly printCallLink: boolean

Prints links in terminal to Weave UI for ops.

Default

true

useCallsComplete

useCallsComplete: boolean

Sends finished calls to the calls/complete endpoint (start+end paired client-side) instead of the legacy call/upsert_batch path.

Default

true

useOTelV2

useOTelV2: boolean

Routes OTel-capable integrations through their OTel variant.

Default

true

traceServerApi

traceServerApi: Api<any>

Defined in: src/weaveClient.ts:537

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. Defined in: src/weaveClient.ts:2165

Parameters

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>

createCall()

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

Defined in: src/weaveClient.ts:1994

Parameters

internalCall

InternalCall

opRef

any

params

any[]

parameterNames

undefined | "useParam0Object" | string[]

thisArg

any

currentCall

callId

string

childSummary

Record<string, any>

displayName?

string

opName?

string

traceId

string

parentCall

{ callId: string; childSummary: Record<string, any>; displayName?: string; opName?: string; traceId: string; } | undefined

startTime

Date

displayName?

string

attributes?

Record<string, any>

eagerCallStart?

boolean = false

Returns

Promise<void>

finishCall()

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

Defined in: src/weaveClient.ts:2068

Parameters

call

InternalCall

result

any

currentCall

callId

string

childSummary

Record<string, any>

displayName?

string

opName?

string

traceId

string

parentCall

{ callId: string; childSummary: Record<string, any>; displayName?: string; opName?: string; traceId: string; } | undefined

summarize

((result) => Record<string, any>) | undefined

endTime

Date

startCallPromise

Promise<void>

Returns

Promise<void>

finishCallWithException()

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

Defined in: src/weaveClient.ts:2110

Parameters

call

InternalCall

error

any

currentCall

callId

string

childSummary

Record<string, any>

displayName?

string

opName?

string

traceId

string

parentCall

{ callId: string; childSummary: Record<string, any>; displayName?: string; opName?: string; traceId: string; } | undefined

endTime

Date

startCallPromise

Promise<void>

Returns

Promise<void>

flush()

flush(): Promise<void>

Deliver all buffered calls to the server. Await before process.exit(). Defined in: src/weaveClient.ts:919

Returns

Promise<void>

get()

get(ref): Promise<any>

Defined in: src/weaveClient.ts:1351

Parameters

ref

ObjectRef

Returns

Promise<any>

getAgentCustomAttributes()

getAgentCustomAttributes(options): Promise<Response<{ attributes?: object[]; has_more?: boolean; limit?: number; offset?: number; }>>

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. Defined in: src/weaveClient.ts:877

Parameters

options

limit?

number Min 1 Max 2000 Default

offset?

number Min 0 Default

query?

Query | null

startedAfter?

string | null

startedBefore?

string | null

Returns

Promise<Response<{ attributes?: object[]; has_more?: boolean; limit?: number; offset?: number; }>>

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

getAgents()

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

List agents with aggregated stats. Defined in: src/weaveClient.ts:593

Parameters

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}`)

getAgentSpans()

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

Query agent spans, optionally filtered by agent name and/or a mongo-style query expression. Defined in: src/weaveClient.ts:671

Parameters

options

GetAgentSpansOptions

Returns

Promise<Response<GetAgentSpansResult>>

Examples

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

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

getAgentSpanStats()

getAgentSpanStats(options): Promise<Response<{ bucket_type?: "number" | "time"; columns?: object[]; end: string; granularity?: number | null; rows?: Record<string, string | number | boolean | null>[]; start: string; timezone: string; }>>

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. Defined in: src/weaveClient.ts:726

Parameters

options

end?

string | null

granularity?

number | null

groupBy?

object[]

metrics

object[]

query?

Query | null

start

string

timezone?

string Default

"UTC"

Returns

Promise<Response<{ bucket_type?: "number" | "time"; columns?: object[]; end: string; granularity?: number | null; rows?: Record<string, string | number | boolean | null>[]; start: string; timezone: string; }>>

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

getAgentTurn()

getAgentTurn(options): Promise<Response<{ agent_name?: string | null; agent_version?: string | null; feedback?: Record<string, any>[] | null; messages?: object[]; provider?: string | null; root_span_name?: string | null; status_code?: "UNSET" | "OK" | "ERROR" | null; total_cost_usd?: number | null; total_duration_ms?: number | null; trace_id: string; }>>

Get data (including messages) for a single turn (by traceId). Defined in: src/weaveClient.ts:760

Parameters

options

GetAgentTurnOptions

Returns

Promise<Response<{ agent_name?: string | null; agent_version?: string | null; feedback?: Record<string, any>[] | null; messages?: object[]; provider?: string | null; root_span_name?: string | null; status_code?: "UNSET" | "OK" | "ERROR" | null; total_cost_usd?: number | null; total_duration_ms?: number | null; trace_id: string; }>>

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

getAgentTurns()

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

Get data (including messages) for many turns (by conversationId). Defined in: src/weaveClient.ts:793

Parameters

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

getAgentVersions()

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

List versions for a given agent. Defined in: src/weaveClient.ts:627

Parameters

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}`)

getCall()

getCall(callId, includeCosts?): Promise<{ attributes: Record<string, any>; deleted_at?: string | null; display_name?: string | null; ended_at?: string | null; exception?: string | null; expire_at?: string | null; id: string; inputs: Record<string, any>; op_name: string; output?: null; parent_id?: string | null; project_id: string; started_at: string; storage_size_bytes?: number | null; summary?: Record<string, any>; thread_id?: string | null; total_storage_size_bytes?: number | null; trace_id: string; turn_id?: string | null; wb_run_id?: string | null; wb_run_step?: number | null; wb_run_step_end?: number | null; wb_user_id?: string | null; wb_username?: string | null; setDisplayName: Promise<void>; }>

Defined in: src/weaveClient.ts:1228

Parameters

callId

string

includeCosts?

boolean = false

Returns

Promise<{ attributes: Record<string, any>; deleted_at?: string | null; display_name?: string | null; ended_at?: string | null; exception?: string | null; expire_at?: string | null; id: string; inputs: Record<string, any>; op_name: string; output?: null; parent_id?: string | null; project_id: string; started_at: string; storage_size_bytes?: number | null; summary?: Record<string, any>; thread_id?: string | null; total_storage_size_bytes?: number | null; trace_id: string; turn_id?: string | null; wb_run_id?: string | null; wb_run_step?: number | null; wb_run_step_end?: number | null; wb_user_id?: string | null; wb_username?: string | null; setDisplayName: Promise<void>; }>

getCalls()

Call Signature

getCalls(options?): Promise<object[]>

Defined in: src/weaveClient.ts:1261

Parameters

options?

GetCallsOptions

Returns

Promise<object[]>

Call Signature

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

Defined in: src/weaveClient.ts:1262

Parameters

options?

CallsFilter

includeCosts?

boolean

limit?

number

Returns

Promise<object[]>

getCallsIterator()

Call Signature

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

Defined in: src/weaveClient.ts:1283

Parameters

options?

CallsFilter

includeCosts?

boolean

limit?

number

Returns

AsyncIterableIterator<CallSchema>

Call Signature

getCallsIterator(options?): AsyncIterableIterator<CallSchema>

Defined in: src/weaveClient.ts:1288

Parameters

options?

GetCallsOptions

Returns

AsyncIterableIterator<CallSchema>

getCallStack()

getCallStack(): CallStack

Defined in: src/weaveClient.ts:1901

Returns

CallStack

getCurrentAttributes()

getCurrentAttributes(): Record<string, any>

Defined in: src/weaveClient.ts:1905

Returns

Record<string, any>

linkPromptToRegistry()

linkPromptToRegistry(prompt, options): Promise<{ version_index: number | null; }>

Link a published prompt version into a registry portfolio. Defined in: src/weaveClient.ts:1510

Parameters

prompt

string | ObjectRef | Prompt

options

aliases?

string[]

targetPath

string

Returns

Promise<{ version_index: number | null; }>

pendingCallCount()

pendingCallCount(): number

Calls buffered client-side but not yet delivered to the server. Defined in: src/weaveClient.ts:924

Returns

number

publish()

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

Defined in: src/weaveClient.ts:1216

Parameters

obj

any

objId?

string

Returns

Promise<ObjectRef>

pushNewCall()

pushNewCall(): object

Defined in: src/weaveClient.ts:1909

Returns

object

currentCall

currentCall: object

currentCall.callId

callId: string

currentCall.childSummary

childSummary: Record<string, any>

currentCall.displayName

optional displayName: string

currentCall.opName

optional opName: string

currentCall.traceId

traceId: string

newStack

newStack: CallStack

parentCall

optional parentCall: object

parentCall.callId

callId: string

parentCall.childSummary

childSummary: Record<string, any>

parentCall.displayName

optional displayName: string

parentCall.opName

optional opName: string

parentCall.traceId

traceId: string

registerCustomRuntime()

registerCustomRuntime(options): Promise<Response<{ api_key_secret: string | null; base_url: string; headers: Record<string, string>; name: string; runtime_ids: object[]; }>>

Parameters

options

RegisterCustomRuntimeOptions

Returns

Promise<Response<{ api_key_secret: string | null; base_url: string; headers: Record<string, string>; name: string; runtime_ids: object[]; }>>

runWithAttributes()

runWithAttributes<T>(attributes, fn): T

Defined in: src/weaveClient.ts:1917

Type Parameters

T

T

Parameters

attributes

Record<string, any>

fn

() => T

Returns

T

runWithCallStack()

runWithCallStack<T>(callStack, fn): T

Defined in: src/weaveClient.ts:1913

Type Parameters

T

T

Parameters

callStack

CallStack

fn

() => T

Returns

T

saveCallEnd()

saveCallEnd(callEnd): void

Defined in: src/weaveClient.ts:1863

Parameters

callEnd

object & object

Returns

void

saveCallStart()

saveCallStart(callStart, opts?): void

Defined in: src/weaveClient.ts:1828

Parameters

callStart

attributes

Record<string, any> Attributes

display_name?

string | null Display Name

id?

string | null Id

inputs

Record<string, any> Inputs

op_name

string Op Name

otel_dump?

Record<string, any> | null Otel Dump

parent_id?

string | null Parent Id

project_id

string Project Id

started_at

string Started At Format date-time

thread_id?

string | null Thread Id

trace_id?

string | null Trace Id

turn_id?

string | null Turn Id

wb_run_id?

string | null Wb Run Id

wb_run_step?

number | null Wb Run Step

wb_user_id?

string | null Wb User Id Do not set directly. Server will automatically populate this field.

opts?

eager?

boolean

Returns

void

saveOp()

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

Defined in: src/weaveClient.ts:1961

Parameters

op

Op<(…args) => any>

objId?

string

Returns

Promise<OpRef>

searchAgents()

searchAgents(options): Promise<Response<{ results: object[]; total_conversations?: number; }>>

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. Defined in: src/weaveClient.ts:835

Parameters

options

agentName?

string | null

conversationId?

string | null

limit?

number Limit Min 0 Max 1000 Default

offset?

number Offset Min 0 Default

query

string

traceId?

string | null

Returns

Promise<Response<{ results: object[]; total_conversations?: number; }>>

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

serializeAudio()

serializeAudio(data, audioType?): Promise<{ _type: "CustomWeaveType"; files: Record<string, string>; load_op: string; weave_type: { type: string; }; }>

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. Defined in: src/weaveClient.ts:1765

Parameters

data

Buffer Raw audio bytes (WAV for best browser compatibility)

audioType?

"wav" = DEFAULT_AUDIO_TYPE File format — currently only ‘wav’ is supported

Returns

Promise<{ _type: "CustomWeaveType"; files: Record<string, string>; load_op: string; weave_type: { type: string; }; }>

updateCall()

updateCall(callId, displayName): Promise<void>

Defined in: src/weaveClient.ts:2148

Parameters

callId

string

displayName

string

Returns

Promise<void>

waitForBatchProcessing()

waitForBatchProcessing(): Promise<void>

Defined in: src/weaveClient.ts:907

Returns

Promise<void>

​Properties

​projectId

​settings

​attributes

​genai

genai.batchOptions

genai.spanProcessor

​printCallLink

Default

​useCallsComplete

Default

​useOTelV2

Default

​traceServerApi

​Methods

​addScore()

​Parameters

predictCallId

scorerCallId

runnableRefUri

scorerOutput

​Returns

​createCall()

​Parameters

internalCall

opRef

params

parameterNames

thisArg

currentCall

callId

childSummary

displayName?

opName?

traceId

parentCall

startTime

displayName?

attributes?

eagerCallStart?

​Returns

​finishCall()

​Parameters

call

result

currentCall

callId

childSummary

displayName?

opName?

traceId

parentCall

summarize

endTime

startCallPromise

​Returns

​finishCallWithException()

​Parameters

call

error

currentCall

callId

childSummary

displayName?

opName?

traceId

parentCall

endTime

startCallPromise

​Returns

​flush()

​Returns

​get()

​Parameters

ref

​Returns

​getAgentCustomAttributes()

​Parameters

options

limit?

Properties

projectId

settings

attributes

genai

printCallLink

useCallsComplete

useOTelV2

traceServerApi

Methods

addScore()

Parameters

Returns

createCall()

Parameters

Returns

finishCall()

Parameters

Returns

finishCallWithException()

Parameters

Returns

flush()

Returns

get()

Parameters

Returns

getAgentCustomAttributes()

Parameters

Returns

Example

getAgents()

Parameters

Returns

Example

getAgentSpans()

Parameters

Returns

Examples

getAgentSpanStats()

Parameters

Returns

Example

getAgentTurn()

Parameters

Returns

Example

getAgentTurns()

Parameters

Returns

Example

getAgentVersions()

Parameters

Returns

Example

getCall()

Parameters

Returns

getCalls()

Call Signature

Call Signature

getCallsIterator()

Call Signature