> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transluce.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Run Metadata

> Read and write metadata on agent runs and transcript groups

Agent runs and transcript groups support arbitrary key-value metadata.
Updates use deep merge — nested dictionaries are merged recursively, preserving existing keys.

See [Metadata](/concepts/metadata) for more on how metadata works in Docent.

## Agent Run Metadata

### Get Metadata

```python theme={null}
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}
```

<ParamField body="collection_id" type="str" required>
  ID of the collection containing the agent run.
</ParamField>

<ParamField body="agent_run_id" type="str" required>
  ID of the agent run.
</ParamField>

### Update Metadata

Deep-merges new metadata into existing values.

```python theme={null}
updated = client.update_agent_run_metadata(
    "my-collection-id",
    "run-id-123",
    {"evaluated": True, "reviewer": "alice"},
)
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="agent_run_id" type="str" required>
  ID of the agent run.
</ParamField>

<ParamField body="metadata" type="dict" required>
  Metadata to merge. Nested dicts are merged recursively; non-dict values are overwritten.
</ParamField>

Returns the full merged metadata dictionary.

### Delete Metadata Keys

```python theme={null}
metadata, not_found = client.delete_agent_run_metadata_keys(
    "my-collection-id",
    "run-id-123",
    keys=["reviewer", "config.temperature"],
)
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="agent_run_id" type="str" required>
  ID of the agent run.
</ParamField>

<ParamField body="keys" type="list[str]" required>
  Keys to remove. Supports dot-delimited paths for nested keys (e.g., `"config.model"`).
</ParamField>

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.

```python theme={null}
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")
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="include_sample_values" type="bool" default="False">
  When `True`, the response also embeds sample values for each field (same
  shape as [Sample Field Values](#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.
</ParamField>

<ParamField body="sample_limit" type="int" default="10">
  Maximum number of sample values per field when `include_sample_values=True`.
</ParamField>

#### Returns

<ResponseField name="fields" type="list[dict]">
  Field descriptors. Each item includes `name`, `type`, and `parquet_indexed`.
</ResponseField>

<ResponseField name="total_runs" type="int">
  Total number of agent runs scanned to build the catalog.
</ResponseField>

### Sample Field Values

Fetch the top values (by frequency) for one or more metadata fields.

```python theme={null}
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")
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="field_names" type="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>"`
</ParamField>

<ParamField body="sample_limit" type="int" default="10">
  Maximum number of sample values to return per field.
</ParamField>

#### Returns

<ResponseField name="samples" type="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.
</ResponseField>

***

## Transcript Group Metadata

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

### Get Metadata

```python theme={null}
metadata = client.get_transcript_group_metadata("my-collection-id", "group-id-456")
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="transcript_group_id" type="str" required>
  ID of the transcript group.
</ParamField>

### Update Metadata

```python theme={null}
updated = client.update_transcript_group_metadata(
    "my-collection-id",
    "group-id-456",
    {"label": "high-quality"},
)
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="transcript_group_id" type="str" required>
  ID of the transcript group.
</ParamField>

<ParamField body="metadata" type="dict" required>
  Metadata to merge.
</ParamField>

### Delete Metadata Keys

```python theme={null}
metadata, not_found = client.delete_transcript_group_metadata_keys(
    "my-collection-id",
    "group-id-456",
    keys=["label"],
)
```

<ParamField body="collection_id" type="str" required>
  ID of the collection.
</ParamField>

<ParamField body="transcript_group_id" type="str" required>
  ID of the transcript group.
</ParamField>

<ParamField body="keys" type="list[str]" required>
  Keys to remove. Supports dot-delimited paths.
</ParamField>