Api

Api(
    api_key: str | None = None,
    host: str | None = None,
    timeout: float = 30.0
) -> None

Python client for the Simpcat public REST API. No external dependencies — uses only stdlib (urllib, json, tomllib).

Credentials are resolved automatically: api_key parameter > SIMPCAT_API_KEY env var > ~/.simpcat/config.toml.

Parameters

api_key — API key. Falls back to SIMPCAT_API_KEY env var, then config file.
host — Server host (e.g. app.simpcat.ai). Falls back to SIMPCAT_HOST env var, then the default production host.
timeout — HTTP request timeout in seconds. Default 30.

Methods

`projects() -> list[dict]`

List all projects.

`runs(*, project=None, name=None, name_contains=None, state=None, tags=None, started_after=None, started_before=None, limit=None, cursor=None) -> RunPage`

List runs with pagination.

project — Filter by project name.
name — Filter by exact run name.
name_contains — Filter by a case-insensitive run-name substring.
state — Filter by "running", "stale", "finished", "failed", "crashed", or "killed".
tags — Dict of tag key/value pairs that must all match.
started_after — Only include runs started after this Unix timestamp in milliseconds.
started_before — Only include runs started before this Unix timestamp in milliseconds.
limit — Page size.
cursor — Pagination cursor from a previous RunPage.

Returns a RunPage with .data (list of run dicts), .has_more, and .next_page().

`all_runs(*, project=None, name=None, name_contains=None, state=None, tags=None, started_after=None, started_before=None) -> list[dict]`

Fetch all runs, exhausting pagination. Convenience wrapper around runs().

`run(run_id: str) -> dict`

Get a single run’s metadata.

`metric_summary(run_id: str) -> dict`

Fetch the canonical per-run metrics summary from /v1/metrics/summary.

Returns a dict with metric_names, histogram_names, latest_metrics, structured latest_points (value, value kind, step, and wall time), summary, current_step, and query_current_step.

`metric(run_id, name, *, format="json", resolution=None, after_step=None, before_step=None, limit=None, last=None, output=None)`

Fetch a single metric’s time-series data via the canonical /v1/metrics/query API.

run_id — Run identifier.
name — Metric name.
format — Response format: "json", "csv", "parquet", "arrow", or "arrow_stream".
resolution — "auto", "raw", or "bucketed". Omit or pass "auto" to choose based on the run’s /v1/metrics/summary step hint.
after_step — Only return steps after this value.
before_step — Only return steps before this value.
limit — Max rows.
last — Return the newest N rows, newest first. Cannot be combined with limit; defaults to raw resolution.
output — File path to stream response to disk (returns Path).

Returns dict for json, str for csv, bytes for binary formats, or Path when output is provided.

For format="json", metric() automatically exhausts server-side pagination and returns a complete {"metric", "resolution", "datapoints"} payload. When output is provided, that complete JSON payload is written atomically to disk.

`metrics(runs, *, metrics=None, format="json", resolution=None, after_step=None, limit=None, output=None)`

Query metrics across multiple runs via the canonical /v1/metrics/query API.

runs — List of run IDs.
metrics — Metric names to include (all if None).
format — Response format.
resolution — "raw" or "bucketed".
after_step — Only return steps after this value.
limit — Max rows.
output — File path to stream response to disk.

For format="json", metrics() automatically exhausts server-side pagination and returns a complete {"data": [...], "count": N} payload. When output is provided, the complete JSON result is written atomically to disk.

`media(run_id: str) -> list[dict]`

List media assets for a run.

`files(run_id: str) -> list[dict]`

List file assets for a run.

`assets(runs, *, types=None, step_range=None) -> dict`

Query assets across multiple runs.

runs — List of run IDs.
types — Asset types to include (all if None).
step_range — (min_step, max_step) tuple filter.