# Import, export, and usage API

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

- [Migrate from W&B, Neptune, or MLflow](/docs/guides/imports.md)
- [Follow the W&B import guide](/docs/guides/wandb-import-guide.md)
- [Understand export and usage limits](/docs/guides/export-usage-limits.md)
- [Understand plan pricing and limits](/docs/guides/pricing-limits-billing.md)
- [Handle errors, pagination, and limits](/docs/api/errors-and-limits.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)
- [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) (current page)
- [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)