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

***

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