API Overview

`class` `FlushStatus`

Status information about the current flush operation.

`class` `PendingJobCounts`

Counts of pending jobs for each type.

`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` `clear_wandb_run_context`

clear_wandb_run_context() → None

Clear wandb run context override. After calling this, calls will fall back to using the global wandb.run (if available) for run_id and step information. Examples:

client = weave.init("my-project")
client.set_wandb_run_context(run_id="my-run-id", step=5)
# ... make some calls ...
client.clear_wandb_run_context()
# Now calls will use global wandb.run again

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

`method` `set_wandb_run_context`

set_wandb_run_context(run_id: 'str', step: 'int | None' = None) → None

Override wandb run_id and step for calls created by this client. This allows you to associate Weave calls with a specific WandB run that is not bound to the global wandb.run symbol. Args:

run_id: The run ID (not including entity/project prefix). The client will automatically add the entity/project prefix.
step: The step number to use for calls. If None, step will not be set. Examples:

client = weave.init("my-project")
client.set_wandb_run_context(run_id="my-run-id", step=5)
# Now all calls will be associated with entity/project/my-run-id at step 5

# Or without a step
client.set_wandb_run_context(run_id="my-run-id")
# Calls will be associated with entity/project/my-run-id with no step

`function` `get_obj_name`

get_obj_name(val: 'Any') → str

`function` `get_parallelism_settings`

get_parallelism_settings() → tuple[int | None, int | None]

`function` `map_to_refs`

map_to_refs(obj: 'Any') → Any

`function` `print_call_link`

print_call_link(call: 'Call') → None

`function` `redact_sensitive_keys`

redact_sensitive_keys(obj: 'Any') → Any

`function` `sanitize_object_name`

sanitize_object_name(name: 'str') → str

Guides

Cookbooks

Reference

Open Source

Community

​API Overview

​class FlushStatus

​class PendingJobCounts

​class WeaveClient

​method __init__

​property num_outstanding_jobs

​method add_cost

​method clear_wandb_run_context

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

​method set_wandb_run_context

​function get_obj_name

​function get_parallelism_settings

​function map_to_refs

​function print_call_link

​function redact_sensitive_keys

​function sanitize_object_name

API Overview

`class` `FlushStatus`

`class` `PendingJobCounts`

`class` `WeaveClient`

`method` `init`

`property` num_outstanding_jobs

`method` `add_cost`

`method` `clear_wandb_run_context`

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

`method` `set_wandb_run_context`

`function` `get_obj_name`

`function` `get_parallelism_settings`

`function` `map_to_refs`

`function` `print_call_link`

`function` `redact_sensitive_keys`

`function` `sanitize_object_name`