# Query runs, metrics, and objects

Use `im.Api(...)` when a script or notebook needs to query runs, fetch bounded metric series, inspect logged objects, or download artifacts — everything a training script's write path does not cover.

## Prerequisites

- An API key with a read scope such as `export:read` for tenant read routes.

## Create an API helper

```python
import instantml as im

api = im.Api(
    base_url="https://api.instantml.ai",
    api_key="instantml_...",
)
```

## Query run summaries

```python
runs = api.query_runs(
    project="cartpole",
    q="tag:baseline status:finished",
    sort_by="metric-best",
    metric_key="eval/return_mean",
    limit=25,
)

for run in runs.items:
    print(run["id"], run.get("name"))
```

Accepted filters:

| Parameter | Meaning |
| --- | --- |
| `project` | Project name. Omit or use `all` for all projects. |
| `status` | `running`, `finished`, `failed`, or `all`. |
| `q` | Shared run search query. Bare text remains implicit `AND`; field filters, exact tags/status, ID prefixes, uppercase booleans, phrases, grouping, field/group exclusion such as `-tag:debug`, and explicit Rust `re:/.../` regex are supported. |
| `sort_by` | `created`, `name`, `status`, `duration`, `metric-latest`, or `metric-best`. |
| `metric_key` | Metric used for metric sorts. |
| `limit` | Page size, 1..100. |
| `cursor` | Cursor returned by the previous `Page`. |
| `max_pages` | Number of pages to read into one `Page`; defaults to 1. |

`query_runs()` returns `Page(items, next_cursor, raw, limit)` and preserves the server's order exactly. Use `iter_runs()` when you want lazy pagination:

```python
for run in api.iter_runs(project="cartpole", q="tag:candidate", page_size=50, max_pages=2):
    print(run["id"])
```

Useful `q` examples:

```text
seed 13
tag:baseline status:finished
name:"long context" -tag:debug
(tag:baseline OR tag:candidate) notes:ablated
re:/seed-(13|14)/
```

> **Note:** `Api.runs()` remains available as the raw compatibility helper. It returns the decoded `/api/runs/summary` payload as a dictionary and also accepts legacy `project_id` and `offset` parameters. Prefer the typed query helpers for new code.

## Fetch metric series

```python
series = api.query_metrics(
    [run["id"] for run in runs.items],
    ["eval/return_mean", "train/loss"],
    step_min=0,
    step_max=1000,
    point_limit=1000,
    buckets=400,
)

for item in series.series:
    print(item["run_id"], item["key"], len(item["metrics"]))
```

`query_metrics()` accepts 1..100 run IDs and 1..25 keys. The SDK calls the bounded metric-series route once per key, preserves caller run and key order, omits empty run/key pairs, and keeps each run/key bounded by `point_limit` before server-side effective caps. `buckets` requests the same M4 downsampling used by high-density dashboard charts.

Metric timestamp windows are not exposed by the current API route. The SDK accepts the future-facing parameters but raises `ValueError` if `time_min`, `time_max`, or `x_axis="time"` are used, so notebooks do not silently receive a different slice than requested.

## Query rich objects

```python
objects = api.query_objects(
    project="cartpole",
    kind="table",
    key="eval/samples",
    limit=25,
)

rows = api.object_rows(objects.items[0]["id"], limit=100)
```

`query_objects()` uses the cross-run `GET /api/objects/explorer` route when the backend exposes it. On older backends it falls back only when you pass a single `run_id`:

```python
objects = api.query_objects(run_id="run-id", kind="table", key="eval/samples")
```

The SDK does not emulate cross-run object search by paging every matching run. That keeps notebook code from accidentally turning a small query into an unbounded fan-out.

## Download artifact bytes

```python
path = api.download_artifact(
    "artifact-id",
    "checkpoints/policy.pt",
)
print(path)
```

The helper creates parent directories and returns the written path. It is the same restore primitive used by checkpoint resume snippets in the dashboard.

## Stay inside read bounds

InstantML keeps list and series reads bounded:

- Run summary and rich-object pages default to 100 rows.
- Raw metric history is requested through metric-specific series endpoints.
- Metric query inputs are capped at 100 run IDs and 25 metric keys.
- Table row reads are capped at 1,000 rows per request.
- Artifact lists are capped.
- Export responses include truncation metadata when limits are hit.

If you need a bulk data movement path, use export or an importer/exporter flow instead of repeatedly fetching every chart series from a notebook.

## Write to an existing run

Use `im.attach_run(...)` when a resume script should continue logging into an existing run, such as a checkpoint fork created by the dashboard or `Api.fork_run(...)`.

```python
run = im.attach_run("child-run-id")
run.log({"train/loss": 0.1}, step=1001)
run.finish()
```

By default, `attach_run(validate=True)` reads `/runs/:id` before returning a run handle. That validation needs read access such as `export:read`. Use `validate=False` only for intentionally write-only credentials or offline attach flows.

## Next steps

- [Log artifacts and checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Export data and usage limits](/docs/guides/export-usage-limits.md)
- [Import runs from other trackers](/docs/guides/imports.md)
- [Metrics series API reference](/docs/api/metrics-series.md)
- [Manage API keys in the dashboard](/docs/dashboard/settings-api-keys.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)
- [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) (current page)
- [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)