# Tables, histograms, evals, and media

Log rich objects when a run needs structured evidence — prediction tables, score distributions, evaluation bundles, and media — alongside its scalar metrics.

Use scalar metrics for one numeric value per step. Use rich objects when the dashboard needs more:

- `run.log_table_object(...)` for prediction samples, eval rows, and compact per-example diagnostics in Run Detail.
- `run.log_objects({"key": im.Histogram.from_values(...)})` for score, confidence, activation, gradient, reward, weight, or latency distributions.
- `run.log_classification_eval(...)` for binary PR/ROC curves, a confusion matrix, per-class metrics, and optional prediction rows.
- `im.Image`, `im.Video`, and `im.Audio` for rollout evidence, generated examples, and audio samples.

For Runs workspace summary panels, keep logging scalar metrics with `run.log_metrics(...)`. For selected-run histogram timelines, log histogram objects under the same key at multiple steps.

## Log tables

Use tables for bounded previewable rows such as predictions, eval samples, or per-example metrics.

```python
import instantml as im

run.log_table_object(
    "eval/predictions",
    ["id", "target", "prediction", "score"],
    [
        {"id": "ex-1", "target": "cat", "prediction": "cat", "score": 0.98},
        {"id": "ex-2", "target": "dog", "prediction": "cat", "score": 0.61},
    ],
    step=10,
)
```

The dashboard fetches table rows through a separate bounded endpoint, so large tables do not slow down the run page.

## Log histograms

Use histograms for distributions such as logits, rewards, gradient norms, or latency samples.

```python
confidence_bins = [index / 8 for index in range(9)]

run.log_objects(
    {
        "eval/confidence": im.Histogram.from_values(
            [0.91, 0.72, 0.88, 0.43],
            bins=confidence_bins,
        )
    },
    step=10,
)
```

Histograms appear as previews in Run Detail and artifact/object surfaces. They are rich evidence objects — a different surface from Runs workspace value-histogram panels, which aggregate scalar metric summaries across runs.

Runs workspace histogram timeline panels can also read a selected run's histogram objects by explicit key. When frames share bin edges, the panel shows a heatmap over steps. When bins differ, it shows a single selected frame instead, so non-comparable frames are not implied to be comparable.

> **Tip:** Keep bin edges stable for a given object key to get a clean timeline heatmap. Adaptive bins still work, but the panel falls back to one frame at a time.

## Log classification evaluations

Use `log_classification_eval(...)` for compact binary classification eval bundles. The SDK stores typed rich-object data rather than screenshots, so Run Detail can render PR/ROC curves, a confusion matrix, per-class metrics, and an optional prediction preview.

```python
run.log_classification_eval(
    "eval/classification",
    y_true=[0, 1, 1, 0],
    y_score=[0.1, 0.8, 0.7, 0.2],
    class_names=["negative", "positive"],
    positive_label="positive",
    split="validation",
    threshold=0.5,
    predictions=[{"id": "ex-1"}],
    step=10,
)
```

The current version is binary-only. `y_score` is the positive-class score, and `y_pred` is optional — it defaults to `score >= threshold`. Confusion matrix rows are true classes and columns are predicted classes, both in `class_names` order. Prediction rows are optional and capped at 100 preview rows.

## Log media objects

Use media objects when the dashboard should treat a stored image, audio, or video as previewable run evidence. Passing a local media path uploads the file bytes and creates the linked rich object for the same run.

```python
run.log_objects(
    {
        "eval/confusion_matrix": im.Image(
            path="outputs/confusion-matrix.png",
            caption="Validation confusion matrix",
        )
    },
    step=10,
)
```

For videos and audio, log the rich object directly when you want Run Detail and artifact surfaces to render a preview:

```python
run.log_objects(
    {"eval/rollout": im.Video(path="outputs/rollout.mp4", caption="Evaluation rollout")},
    step=100,
)
```

Use `upload_file(...)` separately only when you also want a standalone raw file artifact in addition to the rich media object.

Local image, audio, and video objects upload artifact bytes and then create the linked rich object, so the API key needs both `artifacts:write` and `sdk:ingest`. These helpers are not supported in `upload_mode="spool"` because the object link needs the artifact upload response; use `upload_mode="sync"` or the default async mode for those events.

External references such as object-store URIs remain metadata artifacts. They are useful for provenance, but they are not previewable unless bytes are stored through InstantML.

## Log text

Use text values for short generated summaries, explanations, or compact debug output.

```python
run.log_text({"notes/eval": "Policy stabilized after the reward schedule change."}, step=10)
```

## Mix value types in one call

`run.log(...)` classifies values by type before sending requests:

```python
run.log(
    {
        "train/loss": 0.12,
        "notes/eval": "policy stabilized",
    },
    step=2,
)
```

Mixed payloads are deterministic but not atomic across routes. Metrics are sent first, then text, then objects, then files — media values travel inside the object and file requests rather than as a separate batch. If a later request fails, earlier requests may already be stored.

## Next steps

- [Log artifacts and checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Log metrics and steps](/docs/sdk/metrics-steps.md)
- [Explore run evidence in Run Detail](/docs/dashboard/run-detail.md)
- [Query runs, metrics, and objects](/docs/sdk/querying-data.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md) (current page)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)