WeaveClient - Weights & Biases Documentation

Properties

projectId

projectId: string

settings

settings: object

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>

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

string

required

ID of the predict call to attach feedback to

string

required

ID of the scorer call that generated the feedback

string

required

URI of the scorer (Op or Object ref)

any

required

Output of the scorer

Returns

Promise<string>

createCall()

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

Parameters

InternalCall

required

any

required

any[]

required

undefined | "useParam0Object" | string[]

required

any

required

object

required

Hide properties

string

required

Record<string, any>

required

string

required

{…} | undefined

required

Full type:

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

Date

required

string

Record<string, any>

boolean = false

Returns

Promise<void>

finishCall()

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

Parameters

InternalCall

required

any

required

object

required

Hide properties

string

required

Record<string, any>

required

string

required

{…} | undefined

required

Full type:

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

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

required

Date

required

Promise<void>

required

Returns

Promise<void>

finishCallWithException()

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

Parameters

InternalCall

required

any

required

object

required

Hide properties

string

required

Record<string, any>

required

string

required

{…} | undefined

required

Full type:

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

Date

required

Promise<void>

required

Returns

Promise<void>

flush()

flush(): Promise<void>

Deliver all buffered calls to the server. Await before process.exit().

Returns

Promise<void>

get()

get(ref): Promise<any>

Parameters

ObjectRef

required

See 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.

Parameters

object

required

Hide properties

number

Min1Max2000Default

number

Min0Default

Query | null

See Query.

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.

Parameters

GetAgentsOptions = {}

See 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.

Parameters

GetAgentSpansOptions

required

See 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.

Parameters

object

required

Hide properties

string | null

number | null

object[]

required

Query | null

See Query.

string

required

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).

Parameters

GetAgentTurnOptions

required

See 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).

Parameters

GetAgentTurnsOptions

required

See 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.

Parameters

GetAgentVersionsOptions

required

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

Parameters

string

required

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[]>

Parameters

GetCallsOptions

See GetCallsOptions.

Returns

Promise<object[]>

Call Signature

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

Parameters

CallsFilter

See CallsFilter.

boolean

number

Returns

Promise<object[]>

getCallsIterator()

Call Signature

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

Parameters

CallsFilter

See CallsFilter.

boolean

number

Returns

AsyncIterableIterator<CallSchema>

Call Signature

getCallsIterator(options?): AsyncIterableIterator<CallSchema>

Parameters

GetCallsOptions

See GetCallsOptions.

Returns

AsyncIterableIterator<CallSchema>

getCallStack()

getCallStack(): CallStack

Returns

CallStack

getCurrentAttributes()

getCurrentAttributes(): Record<string, any>

Returns

Record<string, any>

linkPromptToRegistry()

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

Link a published prompt version into a registry portfolio.

Parameters

string | ObjectRef | Prompt

required

See ObjectRef.

object

required

Hide properties

string[]

string

required

Returns

Promise<{ version_index: number | null; }>

pendingCallCount()

pendingCallCount(): number

Calls buffered client-side but not yet delivered to the server.

Returns

number

publish()

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

Parameters

any

required

string

Returns

Promise<ObjectRef>

pushNewCall()

pushNewCall(): object

Returns

object

object

required

currentCall.callId

callId: string

currentCall.childSummary

childSummary: Record<string, any>

currentCall.displayName

optional displayName: string

currentCall.opName

optional opName: string

currentCall.traceId

traceId: string

CallStack

required

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

RegisterCustomRuntimeOptions

required

See 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

Type Parameters

Parameters

Record<string, any>

required

() => T

required

Returns

T

runWithCallStack()

runWithCallStack<T>(callStack, fn): T

Type Parameters

Parameters

CallStack

required

() => T

required

Returns

T

saveCallEnd()

saveCallEnd(callEnd): void

Parameters

object & object

required

Returns

void

saveCallStart()

saveCallStart(callStart, opts?): void

Parameters

object

required

Hide properties

Record<string, any>

required

Attributes

string | null

Display Name

string | null

Record<string, any>

required

Inputs

string

required

Op Name

Record<string, any> | null

Otel Dump

string | null

Parent Id

string

required

Project Id

string

required

Started AtFormatdate-time

string | null

Thread Id

string | null

Trace Id

string | null

Turn Id

string | null

Wb Run Id

number | null

Wb Run Step

string | null

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

object

Hide properties

boolean

Returns

void

saveOp()

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

Parameters

Op<(...args) => any>

required

See Op.

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.

Parameters

object

required

Hide properties

string | null

number

LimitMin0Max1000Default

number

OffsetMin0Default

string

required

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.

Parameters

Buffer

required

Raw audio bytes (WAV for best browser compatibility)

"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>

Parameters

string

required

string

required

Returns

Promise<void>

waitForBatchProcessing()

waitForBatchProcessing(): Promise<void>

Returns

Promise<void>

​Properties

​projectId

​settings

​attributes

​genai

genai.batchOptions

genai.spanProcessor

​printCallLink

Default

​useCallsComplete

Default

​useOTelV2

Default

​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

Parameters

Returns

​Call Signature

Parameters

Returns

​getCallsIterator()

​Call Signature

Parameters

Returns

​Call Signature

Parameters

Returns

​getCallStack()

​Returns

​getCurrentAttributes()

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

Call Signature

getCallStack()

Returns

getCurrentAttributes()

Returns

linkPromptToRegistry()

Parameters

Returns

pendingCallCount()

Returns

publish()

Parameters

Returns

pushNewCall()

Returns

registerCustomRuntime()

Parameters