Loading

The Dataset API

A saved report can be published as a read-only API resource, so another system, a spreadsheet or a reporting tool can fetch its results with an API key. Publishing is a deliberate administrative step: saved reports are private working documents until somebody turns this on.

Where to find it

Architect Panel → Data:

  • Report Builder — where the report is built and saved
  • Datastores — the BI Saved Queries datastore, where a saved report is published to the API

How it fits together

  • The report is a saved query from the Report Builder. Each has a key, generated automatically when it is saved, which identifies it to the API.
  • Publishing is a switch on the saved query's record: Published to the API. There is no publish button in the Report Builder itself.
  • The API key must be allowed to read saved queries, with its Saved query access (BI) setting. That is a ceiling, not a grant: every request is still checked against the account the key belongs to, so the key only ever sees rows and fields that account could see.

Publishing a report

  1. Build and save the report in the Report Builder, and check its results.
  2. Open the BI Saved Queries datastore, find the report by name, and turn on Published to the API. The other system will need the report's key, shown as Datasetkey on this record.
  3. On the API key the other system will use, turn on Saved query access (BI). See API.
  4. The other system requests the dataset from the platform's API, naming the dataset scope and the report's key. A request for the list of datasets returns those the key may read.

What the caller gets

The report's results, as data, run at the moment of the request with the key owner's permissions. Charts are not part of the response. A report saved with a Report period returns the same fixed dates every time.

Changing a published report

Editing and re-saving the report in the Report Builder changes what the API returns from the next request, because the key stays the same. If another system depends on the exact columns, treat a change as a change to an interface: build the changed version as a new saved report, publish that, move the caller to its key, then unpublish the old one.

What goes wrong and how to tell

  • "This API key is not allowed to read saved queries.": turn on Saved query access (BI) for the key.
  • "That dataset is not published.": turn on Published to the API for the report.
  • "That dataset is not available to this key.": the key's account cannot see that saved query; check who it is shared with.
  • Fewer rows than in the Report Builder: the key's account has narrower permissions than yours. That is the safeguard working.

Worked example

A finance team wants weekly income by fund in its own spreadsheet. The architect saves "Income by fund" in the Report Builder, turns on Published to the API on its BI Saved Queries record, and creates an API key for a reporting account that can read the income datastore, with Saved query access (BI) on. The spreadsheet's data connection calls the API with that key and the report's key. When the team later asks for an extra column, the architect publishes a new version under a new key and switches the spreadsheet over.

Recommendations

  • Use a dedicated account for API keys, with only the permissions the report needs.
  • Publish only what an external system genuinely needs.
  • Treat published reports as interfaces; change them by publishing a new one.
  • Unpublish reports nobody calls any more.