API Overview

`class` `WeaveClient`

`method` `init`

__init__(
    entity: 'str',
    project: 'str',
    server: 'TraceServerInterface',
    ensure_project_exists: 'bool' = True
)

`property` num_outstanding_jobs

Returns the total number of pending jobs across all executors and the server. This property can be used to check the progress of background tasks without blocking the main thread. Returns:

int: The total number of pending jobs

`method` `add_cost`

add_cost(
    llm_id: 'str',
    prompt_token_cost: 'float',
    completion_token_cost: 'float',
    effective_date: 'datetime | None' = None,
    prompt_token_cost_unit: 'str | None' = 'USD',
    completion_token_cost_unit: 'str | None' = 'USD',
    provider_id: 'str | None' = 'default'
) → CostCreateRes

Add a cost to the current project. Examples:

client.add_cost(llm_id="my_expensive_custom_model", prompt_token_cost=1, completion_token_cost=2)
client.add_cost(llm_id="my_expensive_custom_model", prompt_token_cost=500, completion_token_cost=1000, effective_date=datetime(1998, 10, 3))

Args:

llm_id: The ID of the LLM. eg “gpt-4o-mini-2024-07-18”
prompt_token_cost: The cost per prompt token. eg .0005
completion_token_cost: The cost per completion token. eg .0015
effective_date: Defaults to the current date. A datetime.datetime object.
provider_id: The provider of the LLM. Defaults to “default”. eg “openai”
prompt_token_cost_unit: The unit of the cost for the prompt tokens. Defaults to “USD”. (Currently unused, will be used in the future to specify the currency type for the cost eg “tokens” or “time”)
completion_token_cost_unit: The unit of the cost for the completion tokens. Defaults to “USD”. (Currently unused, will be used in the future to specify the currency type for the cost eg “tokens” or “time”) Returns: A CostCreateRes object. Which has one field called a list of tuples called ids. Each tuple contains the llm_id and the id of the created cost object.

`method` `call`

call(call_id: 'str', include_costs: 'bool' = False) → WeaveObject

`method` `calls`

calls(
    filter: 'CallsFilter | None' = None,
    include_costs: 'bool' = False
) → CallsIter

`method` `create_call`

create_call(
    op: 'str | Op',
    inputs: 'dict[str, Any]',
    parent: 'Call | None' = None,
    attributes: 'dict[str, Any] | None' = None,
    display_name: 'str | Callable[[Call], str] | None' = None,
    use_stack: 'bool' = True,
    _call_id_override: 'str | None' = None
) → Call

Create, log, and push a call onto the runtime stack. Args:

op: The operation producing the call, or the name of an anonymous operation.
inputs: The inputs to the operation.
parent: The parent call. If parent is not provided, the current run is used as the parent.
display_name: The display name for the call. Defaults to None.
attributes: The attributes for the call. Defaults to None.
use_stack: Whether to push the call onto the runtime stack. Defaults to True. Returns: The created Call object.

`method` `delete_all_object_versions`

delete_all_object_versions(object_name: 'str') → int

Delete all versions of an object. Args:

object_name: The name of the object whose versions should be deleted. Returns: The number of versions deleted.

`method` `delete_all_op_versions`

delete_all_op_versions(op_name: 'str') → int

Delete all versions of an op. Args:

op_name: The name of the op whose versions should be deleted. Returns: The number of versions deleted.

`method` `delete_call`

delete_call(call: 'Call') → None

`method` `delete_calls`

delete_calls(call_ids: 'list[str]') → None

Delete calls by their IDs. Deleting a call will also delete all of its children. Args:

`method` `delete_object_version`

delete_object_version(object: 'ObjectRef') → None

`method` `delete_object_versions`

delete_object_versions(object_name: 'str', digests: 'list[str]') → int

Delete specific versions of an object.

call_ids: A list of call IDs to delete. Ex: [“2F0193e107-8fcf-7630-b576-977cc3062e2e”] Args:
object_name: The name of the object whose versions should be deleted.
digests: List of digests to delete. Can include aliases like “latest” or “v0”. Returns: The number of versions deleted.

`method` `delete_op_version`

delete_op_version(op: 'OpRef') → None

`method` `fail_call`

fail_call(call: 'Call', exception: 'BaseException') → None

Fail a call with an exception. This is a convenience method for finish_call.

`method` `feedback`

feedback(
    query: 'Query | str | None' = None,
    reaction: 'str | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → FeedbackQuery

`method` `finish`

finish(
    use_progress_bar: 'bool' = True,
    callback: 'Callable[[FlushStatus], None] | None' = None
) → None

Flushes all background tasks to ensure they are processed. This method blocks until all currently enqueued jobs are processed, displaying a progress bar to show the status of the pending tasks. It ensures parallel processing during main thread execution and can improve performance when user code completes before data has been uploaded to the server. Args:

`method` `finish_call`

finish_call(
    call: 'Call',
    output: 'Any' = None,
    exception: 'BaseException | None' = None,
    op: 'Op | None' = None
) → None

Finalize a call and persist its results. Any values present in call.summary are deep-merged with computed summary statistics (e.g. usage and status counts) before being written to the database.

`method` `flush`

flush() → None

Flushes background asynchronous tasks, safe to call multiple times.

`method` `get`

get(ref: 'ObjectRef', objectify: 'bool' = True) → Any

`method` `get_call`

get_call(
    call_id: 'str',
    include_costs: 'bool' = False,
    include_feedback: 'bool' = False,
    columns: 'list[str] | None' = None
) → WeaveObject

Get a single call by its ID.

use_progress_bar: Whether to display a progress bar during flush. Set to False for environments where a progress bar would not render well (e.g., CI environments).
callback: Optional callback function that receives status updates. Overrides use_progress_bar. Args:
call_id: The ID of the call to get.
include_costs: If true, cost info is included at summary.weave
include_feedback: If true, feedback info is included at summary.weave.feedback
columns: A list of columns to include in the response. If None, all columns are included. Specifying fewer columns may be more performant. Some columns are always included id, project_id, trace_id, op_name, started_at Returns: A call object.

`method` `get_calls`

get_calls(
    filter: 'CallsFilterLike | None' = None,
    limit: 'int | None' = None,
    offset: 'int | None' = None,
    sort_by: 'list[SortByLike] | None' = None,
    query: 'QueryLike | None' = None,
    include_costs: 'bool' = False,
    include_feedback: 'bool' = False,
    columns: 'list[str] | None' = None,
    expand_columns: 'list[str] | None' = None,
    return_expanded_column_values: 'bool' = True,
    scored_by: 'str | list[str] | None' = None,
    page_size: 'int' = 1000
) → CallsIter

Retrieve a list of traced calls (operations) for this project. This method provides a powerful and flexible interface for querying trace data. It supports pagination, filtering, sorting, field projection, and scoring metadata, and can be used to power custom trace UIs or analysis tools. Performance Tip: Specify columns and use filter or query to reduce result size. Args:

filter: High-level filter for narrowing results by fields like op_name, parent_ids, etc.
limit: Maximum number of calls to return.
offset: Number of calls to skip before returning results (used for pagination).
sort_by: List of fields to sort the results by (e.g., started_at desc).
query: A mongo-like expression for advanced filtering. Not all Mongo operators are supported.
include_costs: If True, includes token/cost info in summary.weave.
include_feedback: If True, includes feedback in summary.weave.feedback.
columns: List of fields to return per call. Reducing this can significantly improve performance. (Some fields like id, trace_id, op_name, and started_at are always included.)
scored_by: Filter by one or more scorers (name or ref URI). Multiple scorers are AND-ed.
page_size: Number of calls fetched per page. Tune this for performance in large queries.

Returns:

CallsIter: An iterator over Call objects. Supports slicing, iteration, and .to_pandas().

Example:

calls = client.get_calls(
     filter=CallsFilter(op_names=["my_op"]),
     columns=["inputs", "output", "summary"],
     limit=100,
)
for call in calls:
     print(call.inputs, call.output)

`method` `get_evaluation`

get_evaluation(uri: 'str') → Evaluation

Retrieve a specific Evaluation object by its URI. Evaluation URIs typically follow the format: weave:///entity/project/object/Evaluation:version You can also get the evaluation by its “friendly” name: get_evaluation(“Evaluation:v1”) Args:

uri (str): The unique resource identifier of the evaluation to retrieve.

Returns:

Evaluation: The Evaluation object corresponding to the provided URI.

Raises:

TypeError: If the object at the URI is not an Evaluation instance.
ValueError: If the URI is invalid or the object cannot be found.

Examples:

client = weave.init("my-project")
evaluation = client.get_evaluation("weave:///entity/project/object/my-eval:v1")
print(evaluation.name)

`method` `get_evaluations`

get_evaluations() → list[Evaluation]

Retrieve all Evaluation objects from the current project. Returns:

list[Evaluation]: A list of all Evaluation objects in the current project. Empty list if no evaluations are found or if all conversions fail.

Examples:

client = weave.init("my-project")
evaluations = client.get_evaluations()
print(f"Found {len(evaluations)} evaluations")
for eval in evaluations:
     print(f"Evaluation: {eval.name}")

`method` `get_feedback`

get_feedback(
    query: 'Query | str | None' = None,
    reaction: 'str | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → FeedbackQuery

Query project for feedback. Examples:

# Fetch a specific feedback object.
# Note that this still returns a collection, which is expected
# to contain zero or one item(s).
client.get_feedback("1B4082A3-4EDA-4BEB-BFEB-2D16ED59AA07")

# Find all feedback objects with a specific reaction.
client.get_feedback(reaction="👍", limit=10)

# Find all feedback objects with a specific feedback type with
# mongo-style query.
from weave.trace_server.interface.query import Query

query = Query(
    **{
        "$expr": {
            "$eq": [
                {"$getField": "feedback_type"},
                {"$literal": "wandb.reaction.1"},
            ],
        }
    }
)
client.get_feedback(query=query)

Args:

query: A mongo-style query expression. For convenience, also accepts a feedback UUID string.
reaction: For convenience, filter by a particular reaction emoji.
offset: The offset to start fetching feedback objects from.
limit: The maximum number of feedback objects to fetch. Returns: A FeedbackQuery object.

`method` `purge_costs`

purge_costs(ids: 'list[str] | str') → None

Purge costs from the current project. Examples:

client.purge_costs([ids])
client.purge_costs(ids)

Args:

`method` `query_costs`

query_costs(
    query: 'Query | str | None' = None,
    llm_ids: 'list[str] | None' = None,
    offset: 'int' = 0,
    limit: 'int' = 100
) → list[CostQueryOutput]

Query project for costs.

ids: The cost IDs to purge. Can be a single ID or a list of IDs. Examples:

# Fetch a specific cost object.
# Note that this still returns a collection, which is expected
# to contain zero or one item(s).
client.query_costs("1B4082A3-4EDA-4BEB-BFEB-2D16ED59AA07")

# Find all cost objects with a specific reaction.
client.query_costs(llm_ids=["gpt-4o-mini-2024-07-18"], limit=10)

Args:

query: A mongo-style query expression. For convenience, also accepts a cost UUID string.
llm_ids: For convenience, filter for a set of llm_ids.
offset: The offset to start fetching cost objects from.
limit: The maximum number of cost objects to fetch. Returns: A CostQuery object.

`method` `save`

save(val: 'Any', name: 'str', branch: 'str' = 'latest') → Any

Do not call directly, use weave.publish() instead. Args:

val: The object to save.
name: The name to save the object under.
branch: The branch to save the object under. Defaults to “latest”. Returns: A deserialized version of the saved object.

`class` `Call`

A Call represents a single operation executed as part of a trace. attributes are frozen once the call is created. Use :func:weave.attributes or create_call(..., attributes=...) to populate metadata beforehand. The summary dictionary may be modified while the call is running; its contents are deep-merged with computed summary values when :meth:WeaveClient.finish_call is invoked.

`method` `init`

__init__(
    _op_name: 'str | Future[str]',
    trace_id: 'str',
    project_id: 'str',
    parent_id: 'str | None',
    inputs: 'dict[str, Any]',
    id: 'str | None' = None,
    output: 'Any' = None,
    exception: 'str | None' = None,
    summary: 'dict[str, Any] | None' = &lt;factory&gt;,
    _display_name: 'str | Callable[[Call], str] | None' = None,
    attributes: 'dict[str, Any] | None' = None,
    started_at: 'datetime | None' = None,
    ended_at: 'datetime | None' = None,
    deleted_at: 'datetime | None' = None,
    thread_id: 'str | None' = None,
    turn_id: 'str | None' = None,
    wb_run_id: 'str | None' = None,
    wb_run_step: 'int | None' = None,
    wb_run_step_end: 'int | None' = None,
    _children: 'list[Call]' = &lt;factory&gt;,
    _feedback: 'RefFeedbackQuery | None' = None
) → None

`property` display_name

`property` feedback

`property` func_name

The decorated function’s name that produced this call. This is different from op_name which is usually the ref of the op.

`property` op_name

`property` ref

`property` ui_url

`method` `apply_scorer`

apply_scorer(
    scorer: 'Op | Scorer',
    additional_scorer_kwargs: 'dict[str, Any] | None' = None
) → ApplyScorerResult

apply_scorer is a method that applies a Scorer to a Call. This is useful for guarding application logic with a scorer and/or monitoring the quality of critical ops. Scorers are automatically logged to Weave as Feedback and can be used in queries & analysis. Args:

scorer: The Scorer to apply.
additional_scorer_kwargs: Additional kwargs to pass to the scorer. This is useful for passing in additional context that is not part of the call inputs.useful for passing in additional context that is not part of the call inputs. Returns: The result of the scorer application in the form of an ApplyScorerResult.

class ApplyScorerSuccess:

 - <b>`    result`</b>:  Any

 - <b>`    score_call`</b>:  Call

Example usage:

my_scorer = ... # construct a scorer
prediction, prediction_call = my_op.call(input_data)
result, score_call = prediction.apply_scorer(my_scorer)

`method` `children`

children(page_size: 'int' = 1000) → CallsIter

Get the children of the call. Args:

page_size: Tune performance by changing the number of calls fetched at a time. Returns: An iterator of calls.

`method` `delete`

delete() → bool

Delete the call.

`method` `remove_display_name`

remove_display_name() → None

`method` `set_display_name`

set_display_name(name: 'str | None') → None

Set the display name for the call. Args:

name: The display name to set for the call. Example:

result, call = my_function.call("World")
call.set_display_name("My Custom Display Name")

`method` `to_dict`

to_dict() → CallDict

`function` `PaginatedIterator`

PaginatedIterator(*args, **kwargs)

Guides

Cookbooks

Reference

Open Source

Community

​API Overview

​class WeaveClient

​method __init__

​property num_outstanding_jobs

​method add_cost

​method call

​method calls

​method create_call

​method delete_all_object_versions

​method delete_all_op_versions

​method delete_call

​method delete_calls

​method delete_object_version

​method delete_object_versions

​method delete_op_version

​method fail_call

​method feedback

​method finish

​method finish_call

​method flush

​method get

​method get_call

​method get_calls

​method get_evaluation

​method get_evaluations

​method get_feedback

​method purge_costs

​method query_costs

​method save

​class Call

​method __init__

​property display_name

​property feedback

​property func_name

​property op_name

​property ref

​property ui_url

​method apply_scorer

​method children

​method delete

​method remove_display_name

​method set_display_name

​method to_dict

​function PaginatedIterator

API Overview

`class` `WeaveClient`

`method` `init`

`property` num_outstanding_jobs

`method` `add_cost`

`method` `call`

`method` `calls`

`method` `create_call`

`method` `delete_all_object_versions`

`method` `delete_all_op_versions`

`method` `delete_call`

`method` `delete_calls`

`method` `delete_object_version`

`method` `delete_object_versions`

`method` `delete_op_version`

`method` `fail_call`

`method` `feedback`

`method` `finish`

`method` `finish_call`

`method` `flush`

`method` `get`

`method` `get_call`

`method` `get_calls`

`method` `get_evaluation`

`method` `get_evaluations`

`method` `get_feedback`

`method` `purge_costs`

`method` `query_costs`

`method` `save`

`class` `Call`

`method` `init`

`property` display_name

`property` feedback

`property` func_name

`property` op_name

`property` ref

`property` ui_url

`method` `apply_scorer`

`method` `children`

`method` `delete`

`method` `remove_display_name`

`method` `set_display_name`

`method` `to_dict`

`function` `PaginatedIterator`