InstantMLDocs

Import, export, and usage API

Run migration importers, export bounded data, and inspect usage guardrails.

Open .md

Migrate tracked data in, export bounded archives out, and inspect the usage guardrails that gate writes.

Authenticate with an Authorization: Bearer instantml_... API key or a browser session. Exports need the export:read scope, importer writes need imports:write, import history reads need export:read or imports:write, and usage routes need usage:read.

Export data

bash
curl "https://api.instantml.ai/api/export?project=cartpole&status=finished&q=tag%3Abaseline%20NOT%20tag%3Adebug" \
  -H "Authorization: Bearer instantml_..."

API keys need export:read; browser sessions need viewer or higher role.

Export accepts the same bounded run filters as GET /runs, including project, status, sort_by, metric_key, and the shared run-search q language. Search supports bare text, tag:/tags:, notes:, config:, metadata:, status:, id:, uppercase AND/OR/NOT, field/group exclusion with -, quoted phrases, and explicit Rust regex such as re:/seed-(13|14)/. The deprecated Node compatibility API supports the non-regex subset and returns run_search_regex_unsupported for completed regex queries.

Selected-run export accepts run_ids (or the legacy alias runs) as a comma-separated UUID list capped at 100 runs:

http
GET /api/export?format=csv&run_ids=0af...,7db...
Authorization: Bearer instantml_...

format=json is the default. format=csv returns a flat, spreadsheet-safe record stream with Content-Disposition, Cache-Control: private, no-store, X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox, and X-InstantML-Export-Truncated headers. JSON exports use the same download and cache-control headers.

Response shape:

json
{
  "version": 1,
  "exported_at": "2026-05-16T00:00:00Z",
  "organizations": [],
  "projects": [],
  "runs": [],
  "metric_series": [],
  "metrics": [],
  "attributes": [],
  "artifacts": [],
  "table_object_rows": [],
  "imports": [],
  "limits": {},
  "truncated": false
}

Export is bounded to 500 filter-selected runs, 100 selected run IDs, 100,000 metric points, 25,000 metric-series summaries, 25,000 attributes, 10,000 artifacts, 25,000 table rows, 500 import records, and 25 MiB CSV responses. If truncated is true, or the X-InstantML-Export-Truncated header is true, narrow the filters before treating the file as a complete archive.

Read the usage summary

http
GET /api/usage
Authorization: Bearer instantml_...

Requires an unrestricted org API key with usage:read or an owner/admin browser session.

Usage includes:

  • Plan catalog.
  • Current org plan.
  • Current UTC calendar-month metric usage.
  • Current UTC calendar-month API request usage.
  • Retained projects, runs, metric series, artifacts, API keys, and seats.
  • Exact artifact bytes when available.
  • Exact InstantML-hosted ClickHouse table bytes when available.
  • Blocked-at-limit storage estimates. Customer-owned (BYOC) storage guardrails count only InstantML-owned artifact bytes and never include customer-owned ClickHouse database bytes.
  • Billing precision metadata.

Metric-point and API-request usage reset monthly. Most other counters are retained resources. Free and non-billable orgs are blocked at the monthly API request allowance, while paid Pro/Premium request overage is Stripe-metered. Short-window 429 rate limits protect the service independently from monthly request quotas.

Export usage records

http
GET /api/usage/export
Authorization: Bearer instantml_...

Use usage export for account audits and support handoff. It follows the same org and permission rules as the usage summary.

Run importers

Import v2 is the recommended migration API for SDK/CLI-driven imports:

http
POST /api/imports/jobs
GET  /api/imports/jobs/{import_id}
POST /api/imports/jobs/{import_id}/chunks
POST /api/imports/jobs/{import_id}/commit
POST /api/imports/jobs/{import_id}/cancel
Authorization: Bearer instantml_...

The create response returns an import job; read it back with GET /api/imports/jobs/{import_id} to poll status and progress. Chunk uploads carry canonical runs, metric points, artifact references, warnings, source identity, and a final marker. Commit is allowed only after the final chunk has passed validation. Use cancel for abandoned dry-runs. Accepted chunk payloads count toward retained operational storage, are checked against storage plan capacity when appended, and are bounded by a per-job staged-payload byte ceiling.

Committed external artifact references are stored as legacy raw artifact rows and mirrored into run-level metadata-only versioned artifact bundles. The catalog entries have external manifest references and lineage edges, but no InstantML download until bytes are uploaded separately.

Legacy transformed JSON routes remain supported for compatibility:

  • POST /api/imports/neptune
  • POST /api/imports/wandb
  • POST /api/imports/mlflow

Importer write routes need API keys with imports:write. Reading a job with GET /api/imports/jobs/{import_id} needs export:read or imports:write. CLI device login grants import, artifact, export, and SDK ingest scopes so one login can dry-run imports, commit them, sync TensorBoard, and log normal training runs.

Read import history

http
GET /api/imports
Authorization: Bearer instantml_...

Import history is read-only. It accepts a same-org browser session, or an API key with export:read or imports:write. Reserve imports:write for keys that create new W&B, MLflow, or Neptune imports; a read-only export:read key is enough to audit history.

Practical migration flow:

  1. Run the Python CLI locally against W&B, Neptune Exporter Parquet, MLflow JSON, or TensorBoard event files.
  2. Upload a dry-run Import v2 job.
  3. Verify projects, runs, metrics, configs, tags, notes, artifacts, warnings, and counts.
  4. Commit once the mapping is trusted.

Imports can write many records. Treat importer retries as operational jobs and keep the returned import ID with logs or support tickets.

Next steps