# Reports API

Automate workspace-scoped reports — documents with ordered JSON blocks for
headings, paragraphs, markdown, code, callouts, images, and live panel grids.
Legacy `llm_summary` blocks can still render in existing reports, but new
authoring should use the dashboard-supported block set.

Report routes accept a browser session with workspace membership. Bearer API
keys also work for automation: report read routes accept any same-org API key or
same-org session, and write routes accept API keys belonging to the workspace
org. Report reads are a control-plane exception to the normal `export:read`
tenant-read rule. Report API-key writes do not currently require a separate
`reports:write` scope. Report editing is still primarily a dashboard workflow.

## List reports

```bash
curl "https://api.instantml.ai/api/reports?limit=50&offset=0" \
  -H "Authorization: Bearer instantml_..."
```

Optional `project` filters by project ID. The response includes summaries,
pagination fields, visibility, share state, and block counts.

## List report panels

```http
GET /api/reports/panels
Authorization: Bearer instantml_...
```

Returns the workspace's flattened panel inventory for the dashboard "add panel
from another report" workflow. Each entry includes `report_id`,
`report_title`, `panel_index`, and `panel_spec`. The route accepts a same-org
session or API key and does not expose private report contents through public
share tokens.

## Create a report

```http
POST /api/reports
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "title": "RL checkpoint readout",
  "description": "Fork candidate and artifact evidence.",
  "visibility": "org",
  "blocks": [
    { "kind": "heading", "level": 1, "text": "RL checkpoint readout" },
    { "kind": "paragraph", "text": "Seed 44 reached a stable return profile." },
    {
      "kind": "panel_grid",
      "runsets": [{ "name": "demo", "projects": ["demo"] }],
      "panels": [
        { "type": "line", "metric_key": "eval/return_mean", "runset_index": 0 }
      ]
    }
  ]
}
```

`title` is required. `visibility` is `private`, `org`, or `public`. `blocks`
must be an array when provided. The dashboard defaults new reports to private
until the user changes visibility or creates a share link.

## Read, update, or delete one report

```http
GET /api/reports/{report_id}
PATCH /api/reports/{report_id}
DELETE /api/reports/{report_id}
```

`PATCH` accepts any subset of `title`, `description`, `visibility`, and
`blocks`, but the body cannot be empty. The dashboard auto-saves edits through
this route.

Reports with `visibility: "public"` can be read by ID without auth. Private
and org-visible reports require workspace access unless a share token is used.

## Share and read publicly

```http
POST /api/reports/{report_id}/share
GET /api/reports/share/{share_token}
GET /api/reports/{report_id}?share={share_token}
```

Creating or rotating a share link returns the updated report with its
`share_token`. Public share reads are limited to the shared report.

## Export markdown

```http
GET /api/reports/{report_id}/markdown
GET /api/reports/{report_id}/markdown?share={share_token}
```

Markdown export renders text blocks, code blocks, panel-grid placeholders, and
legacy stored LLM-summary text into a portable `.md` response.

## Stay inside block limits

Reports are validated before persistence. Each report has a bounded number of
blocks, per-block size limits, and a fixed set of supported block and panel
types. Current limits are 256 blocks, 256 KiB total block JSON, and 32 KiB per
block. Invalid blocks return `400` with a validation message.

## Next steps

- [Write reports in the dashboard](/docs/dashboard/reports.md)
- [Build research dashboards](/docs/dashboard/research-dashboards.md)
- [Embed run charts in other tools](/docs/api/iframe-embeds.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) (current page)
- [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)
**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)