Public Dataset API

The Public Dataset API has two data paths:

• Query returns a bounded JSON result. Use it for application reads and small analytical questions.
• Current returns the complete current Parquet snapshot. Use it for model training, bulk analysis, and scheduled local refreshes.

Both require a public dataset to be connected to your workspace. Open the dataset’s canonical public page, choose Use dataset, then create a personal mr_use_… key in its API access section once the page says Using in workspace.

mr_use_… is the key for connected public datasets. It is distinct from the legacy SDK/hosted-table mr_live_… subscription key and the mr_cli_… device credential; neither legacy key type is accepted by the Public Dataset API.

Search the public catalog

GET /api/v2/public/datasets?q=weather&limit=20

Catalog metadata is public. It returns dataset identity, publisher, licence, tables, public schema metadata, and canonical URLs. It does not reveal which workspaces use a dataset.

Query a table

POST /api/v2/public/tables/{table_id}/query
x-api-key: mr_use_…
content-type: application/json

{
  "columns": ["city", "date", "temperature"],
  "filters": [
    { "column": "date", "operator": "gte", "value": "2026-08-01" }
  ],
  "order_by": [{ "column": "temperature", "direction": "desc" }],
  "limit": 100
}

Successful responses are JSON:

{
  "schema_version": "mostlyright-public-table-query.v1",
  "query_id": "qry_…",
  "table": {
    "id": "…",
    "version_id": "…",
    "content_digest": "sha256:…",
    "published_at": "2026-08-23T10:00:00Z"
  },
  "columns": [{ "name": "temperature", "type": "float64" }],
  "rows": [{ "temperature": 31.2 }],
  "execution": {
    "returned_rows": 1,
    "scanned_bytes": 184320,
    "elapsed_ms": 42,
    "truncated": false
  }
}

The request is a closed query grammar. It is not SQL. Unknown columns, unsupported operators, and invalid values are rejected before a table is scanned.

Download the current Parquet version

GET /api/v2/public/tables/{table_id}/current
x-api-key: mr_use_…

The response body is application/vnd.apache.parquet. It carries a strong ETag, Content-Digest, Content-Length, and X-Request-Id. Send If-None-Match to refresh efficiently. See Use a public dataset for a DuckDB example.

Errors and limits

All JSON errors contain schema_version, error, and request_id.

Status	Meaning
401	Missing, invalid, revoked, or wrong key type.
404	The table is unavailable to this workspace, no longer public, or unknown. These cases are intentionally indistinguishable.
413	The requested artifact or result is too large. Refine the query or use Current for bulk data.
429	Rate limit reached. Respect Retry-After.
503, 504	Temporary service condition. Retry with backoff.

Query results have row, byte, and time limits. The response tells you when a result was truncated. Use Current and local DuckDB for large scans.

Complete contract

The machine-readable OpenAPI document is the source for REST request and response schemas. This API remains the application and script path and uses a workspace mr_use_ key. The legacy SDK and hosted-table API continue to use mr_live_… separately. MCP is an OAuth connection that delegates to the same bounded query services; it never accepts a pasted API key. See Connect an AI tool.