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, limit=None, cursor=None) -> RunPage

List runs with pagination.

• project — Filter by project name.
• 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) -> 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, summary, current_step, and query_current_step.

metric(run_id, name, *, format="json", resolution=None, after_step=None, limit=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.
• limit — Max rows.
• 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.