# Iframe run embeds Place a focused, interactive InstantML run board inside an internal portal, notebook, wiki, or review page without loading the full dashboard. ![Embedded run charts inside a parent website](/docs/assets/images/product/embed-runs-iframe.png) Embeds are intentionally short-lived and server-created. Your backend passes explicit run IDs, one allowed parent origin, and an InstantML API key with `export:read`. InstantML returns a copy-once iframe URL whose fragment contains the embed bearer token. ## Create an embed session ```bash curl -X POST https://api.instantml.ai/api/embed/sessions \ -H "Authorization: Bearer instantml_..." \ -H "Content-Type: application/json" \ -d '{ "run_ids": [ "4d14b2ea-7f49-4c7b-8d38-bb8437b5b029", "767f8f0e-2d72-4ff8-b5be-01d06c93d265" ], "allowed_parent_origin": "https://portal.example.com", "ttl_seconds": 900, "options": { "max_panels": 8, "metric_point_limit": 500, "theme": "system" } }' ``` The response includes: ```json { "embed_session": { "id": "86d2c75c-0c88-4d7c-8711-e461a77d4edc", "expires_at": "2026-06-25T21:45:00Z", "allowed_parent_origin": "https://portal.example.com", "run_count": 2, "iframe_src": "https://instantml.ai/embed/runs/86d2c75c-0c88-4d7c-8711-e461a77d4edc#token=instantml_embed_..." }, "embed_token": "instantml_embed_..." } ``` > **Warning:** Treat both `iframe_src` and `embed_token` as bearer secrets. InstantML stores only a hash of the embed token and never returns the plaintext again. ## Add the iframe Render the returned `iframe_src` from the exact origin you passed as `allowed_parent_origin`: ```html ``` The embed page removes the fragment token from browser history before it makes API calls. Data requests use embed-only routes, omit browser credentials, and return bounded chart data only for the selected run IDs. ## Know what renders The generated embed board reuses the Runs workspace's bounded chart projection. It can render: - Line charts for metric trends, with smoothing, range zoom, y-axis controls, legends, and hover inspection. - Latest-value bar charts, dot plots, and value histograms across the embedded run set. - Scatter plots and grouped distributions when the generated panel includes bounded field specs. Logged histogram timelines, rank/distributed heatmaps, table/media panels, and chart exports are not available in iframes yet. Embeds are intentionally inspection-only: viewers can hover, zoom line charts, and refresh the data, but they cannot mutate dashboards or download plotted data from the iframe. ## Respect limits and security rules - API key: must be an API key, not a browser session, and must include `export:read`. - Run access: project-scoped keys can embed only runs in the scoped project. - Parent origin: must match one exact origin. Hosted embeds require HTTPS and reject wildcards, path/query strings, credentials, and InstantML-owned app/API origins. - TTL: defaults to 15 minutes and is capped at 60 minutes. - Size caps: up to 100 runs, 8 panels, and 500 points per run/series in v1. Create-time `options.max_panels` and `options.metric_point_limit` are caps; iframe data requests can narrow them but cannot widen them. - Headers: non-embed InstantML pages keep anti-framing headers. The embed route emits a per-session `frame-ancestors` policy for the approved parent origin. - Actions: embeds are read-only. Dashboard navigation, saved-view edits, run-stop controls, artifact downloads, and plotted CSV/SVG exports are not available inside the iframe. ## Debug failure states Unknown sessions fail closed and cannot be framed. Known expired or disabled sessions can still frame only on the stored parent origin so viewers see a clear no-data state instead of a blank parent page. Data APIs continue to reject expired, revoked, or source-key-invalid sessions. If the iframe does not render, check: - The parent page origin exactly matches `allowed_parent_origin`. - The iframe `src` still contains the fragment token on first load. - The embed session has not expired. - The source API key still exists, is not revoked, and still has `export:read`. - Your backend did not place the token in a query string or server-side log. ## Next steps - [Create and scope API keys](/docs/dashboard/settings-api-keys.md) - [Share findings with reports](/docs/api/reports.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) (current page) - [Import Export Usage](/docs/api/import-export-usage.md) - [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)