# Dashboard control-state API

Store human UI preferences — the selected project and saved workspace views —
through the dashboard control-state routes.

Authenticate with a browser session (`instantml_session` cookie) that has
organization membership. SDK API keys are not accepted on these routes, with
one exception: `POST /api/workspace-view-data` also accepts an API key with the
`export:read` scope.

## Read and save the project preference

Read:

```bash
curl https://api.instantml.ai/api/dashboard/preferences \
  -H "Cookie: instantml_session=..."
```

Response when saved:

```json
{
  "preferences": {
    "selected_project": "hosted-scale-data",
    "updated_at": "2026-05-17T00:00:00Z"
  }
}
```

Save:

```http
PUT /api/dashboard/preferences
Cookie: instantml_session=...
Content-Type: application/json

{
  "selected_project": "cartpole"
}
```

Set `selected_project` to `null` to clear the preference.

## List workspace views

```http
GET /api/workspace-views?limit=50
Cookie: instantml_session=...
```

List rows are summaries and do not include the full saved layout payload.

## Create a workspace view

```http
POST /api/workspace-views
Cookie: instantml_session=...
Content-Type: application/json

{
  "name": "Daily comparison",
  "project": "cartpole",
  "payload": {
    "schema_version": 1,
    "tab": "runs",
    "workspace_view": {}
  }
}
```

The payload must be a JSON object and must serialize to at most 64 KiB.

## Read or update one workspace view

```http
GET /api/workspace-views/{view_id}
Cookie: instantml_session=...
```

```http
PUT /api/workspace-views/{view_id}
Cookie: instantml_session=...
Content-Type: application/json

{
  "name": "Daily eval pass"
}
```

Update accepts any subset of `name`, `project`, and `payload`.

## Delete a workspace view

```http
DELETE /api/workspace-views/{view_id}?expected_updated_at=2026-05-17T00:00:00Z
Cookie: instantml_session=...
```

The `expected_updated_at` query parameter is required and must match the last
`updated_at` you observed; a stale value returns `409` so concurrent edits are
not silently destroyed. A successful delete returns:

```json
{
  "deleted": true,
  "view_id": "86d2c75c-0c88-4d7c-8711-e461a77d4edc",
  "deleted_at": "2026-05-17T00:00:00Z"
}
```

## Export a workspace view

```http
GET /api/workspace-views/{view_id}/export
Cookie: instantml_session=...
```

Returns a portable JSON envelope you can store, share, or re-import:

```json
{
  "kind": "instantml.workspace_view",
  "schema_version": 1,
  "exported_at": "2026-05-17T00:00:00Z",
  "source": { "product": "instantml", "format": "workspace_view" },
  "view": {
    "name": "Daily comparison",
    "project": "cartpole",
    "payload": {}
  },
  "integrity": { "payload_sha256": "64-hex" }
}
```

`integrity.payload_sha256` lets the importer detect payload corruption or
tampering before applying the view.

## Import a workspace view

```http
POST /api/workspace-views/import
Cookie: instantml_session=...
Content-Type: application/json

{
  "exported_view": { "kind": "instantml.workspace_view", "schema_version": 1, "...": "..." },
  "dry_run": true,
  "name": "Imported comparison",
  "project": "cartpole"
}
```

`exported_view` (a full export envelope) and `dry_run` are required. Optional
fields: `name` and `project` override the exported values; `existing_view_id`
plus `expected_updated_at` target an existing view for overwrite; and
`conflict_strategy` is `create` (default) or `replace`. A stale
`expected_updated_at` returns `409`.

The response reports what happened (or would happen when `dry_run` is true):

```json
{
  "dry_run": true,
  "action": "create",
  "name": "Imported comparison",
  "project": "cartpole",
  "payload_bytes": 2048,
  "warnings": [],
  "workspace_view": null
}
```

Run a `dry_run` first, review `warnings`, then repeat with `dry_run: false` to
persist; the persisted call returns the created or updated `workspace_view`.

## Fetch data for a portable view

```http
POST /api/workspace-view-data
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "view": { "schema_version": 1, "tab": "runs", "workspace_view": {} },
  "run_ids": ["4d14b2ea-7f49-4c7b-8d38-bb8437b5b029"],
  "options": { "max_panels": 8, "metric_point_limit": 500 }
}
```

Unlike the other routes on this page, this data read accepts an API key with
`export:read` or a browser session. Send the view payload (`view`) and explicit
`run_ids`; `options.max_panels` and `options.metric_point_limit` cap the
projection. The response's `view_data` object contains `schema_version`,
`generated_at`, `run_ids`, `runs`, `metric_keys`, `metric_series`, `panels`,
`warnings`, and `limits` — a bounded projection sized for rendering the view
without further queries. Runs that are missing or not visible to the caller
return `404`.

## Understand demo behavior

Shared demo sessions are read-only and cannot save dashboard control state.
If the control-state API is temporarily unavailable, the dashboard keeps the
current page usable and retries later.

## Next steps

- [Work in the Runs workspace](/docs/dashboard/runs-workspace.md)
- [Authenticate API calls](/docs/api/authentication.md)
- [Query run summaries over HTTP](/docs/api/projects-runs.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)
- [Dashboard Control State](/docs/api/dashboard-control-state.md) (current page)
**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)