Skip to main content
Agent runs and transcript groups support arbitrary key-value metadata. Updates use deep merge — nested dictionaries are merged recursively, preserving existing keys. See Metadata for more on how metadata works in Docent.

​
Agent Run Metadata

​
Get Metadata

from docent import Docent

client = Docent()

metadata = client.get_agent_run_metadata("my-collection-id", "run-id-123")
print(metadata)  # {"model": "gpt-4", "score": 0.95}
​
collection_id
str
required
ID of the collection containing the agent run.
​
agent_run_id
str
required
ID of the agent run.

​
Update Metadata

Deep-merges new metadata into existing values. 
updated = client.update_agent_run_metadata(
    "my-collection-id",
    "run-id-123",
    {"evaluated": True, "reviewer": "alice"},
)
​
collection_id
str
required
ID of the collection.
​
agent_run_id
str
required
ID of the agent run.
​
metadata
dict
required
Metadata to merge. Nested dicts are merged recursively; non-dict values are overwritten.
Returns the full merged metadata dictionary.

​
Delete Metadata Keys

metadata, not_found = client.delete_agent_run_metadata_keys(
    "my-collection-id",
    "run-id-123",
    keys=["reviewer", "config.temperature"],
)
​
collection_id
str
required
ID of the collection.
​
agent_run_id
str
required
ID of the agent run.
​
keys
list[str]
required
Keys to remove. Supports dot-delimited paths for nested keys (e.g., "config.model").
Returns a tuple of (metadata_after_deletion, keys_not_found).

​
Discover Metadata Fields

Use these methods to inspect which metadata fields exist on agent runs in a collection, and to pull sample values for specific fields.

​
List Available Fields

Returns the catalog of agent-run metadata fields with their names, types, and whether each field is parquet-indexed. 
response = client.get_metadata_fields("my-collection-id")

for field in response["fields"]:
    print(field["name"], field["type"])

print(f"{response['total_runs']} runs scanned")
​
collection_id
str
required
ID of the collection.
​
include_sample_values
bool
default:"False"
When True, the response also embeds sample values for each field (same shape as Sample Field Values). For new code, prefer calling get_metadata_field_samples for just the fields you care about — it avoids paying the cost of sampling every field in the catalog.
​
sample_limit
int
default:"10"
Maximum number of sample values per field when include_sample_values=True.

​
Returns

​
fields
list[dict]
Field descriptors. Each item includes name, type, and parquet_indexed.
​
total_runs
int
Total number of agent runs scanned to build the catalog.

​
Sample Field Values

Fetch the top values (by frequency) for one or more metadata fields. 
response = client.get_metadata_field_samples(
    "my-collection-id",
    field_names=["model", "scores.reward", "label.review.quality"],
    sample_limit=10,
)

for name, entry in response["samples"].items():
    print(name, entry["total_unique_values"])
    for sample in entry["sample_values"]:
        print(f"  {sample['value']}: {sample['count']} runs")
​
collection_id
str
required
ID of the collection.
​
field_names
list[str]
required
Field names to sample. Each name may be:
  • Fully qualified: "metadata.foo.bar"
  • Bare: "foo.bar" — treated as shorthand for "metadata.foo.bar"
  • "tag" (the bare word)
  • "label.<set>.<key>"
​
sample_limit
int
default:"10"
Maximum number of sample values to return per field.

​
Returns

​
samples
dict[str, dict]
Mapping keyed by the original (un-normalized) field name you passed in. Each value contains:
  • sample_values — list of { "value": str, "count": int } entries, ordered by descending frequency.
  • total_unique_values — total number of distinct values for the field.

​
Transcript Group Metadata

Transcript groups share the same metadata API pattern as agent runs.

​
Get Metadata

metadata = client.get_transcript_group_metadata("my-collection-id", "group-id-456")
​
collection_id
str
required
ID of the collection.
​
transcript_group_id
str
required
ID of the transcript group.

​
Update Metadata

updated = client.update_transcript_group_metadata(
    "my-collection-id",
    "group-id-456",
    {"label": "high-quality"},
)
​
collection_id
str
required
ID of the collection.
​
transcript_group_id
str
required
ID of the transcript group.
​
metadata
dict
required
Metadata to merge.

​
Delete Metadata Keys

metadata, not_found = client.delete_transcript_group_metadata_keys(
    "my-collection-id",
    "group-id-456",
    keys=["label"],
)
​
collection_id
str
required
ID of the collection.
​
transcript_group_id
str
required
ID of the transcript group.
​
keys
list[str]
required
Keys to remove. Supports dot-delimited paths.