Agent Run Metadata

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.

Getting Started

Collections

Agent Runs

DQL

Feedback & Labels

More

Legacy

Agent Run Metadata