Skip to main content

List reports

GET https://api.rollstack.com/public/v1/reports

The reports the user can see, of every type, newest first. Each report's type tells which endpoints work on it: the slides agent, exports, content, datasheets, parameters, templates, duplicating and ownership transfer take SlideDeck reports only, and syncs take the other types only. You can filter by folderId, name and type; when several are set, all must match, and name matching ignores case. Answers up to limit reports, 50 by default and 200 at most, and a nextCursor: pass it as cursor for the next page, until it is null.

Requires the slide_decks:read scope.

Operation ID: listReports.

Query parameters

  • folderId (string): Only return reports directly in this folder, by its id from listFolders. Reports in its subfolders aren't included. Example: a3d5e7f9-1b2c-4d6e-8f0a-1b2c3d4e5f6a.
  • name (string): Only return reports whose name contains this text, ignoring case: review matches Q3 Business Review. Example: business review.
  • type (string): Only return reports of this type, such as SlideDeck for the reports that the slides agent, exports and datasheets work on. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck. Example: SlideDeck.
  • limit (integer): Maximum number of reports to return on this page, from 1 to 200. Defaults to 50.
  • cursor (string): Where to continue the list: pass the nextCursor returned with the previous page to get the next one. Omit it for the first page. Example: 6c1f9a2e-3b4d-4e8f-9a1b-2c3d4e5f6a7b.

Response 200

Success

application/json

  • data (array of object, required): The reports on this page, of every type, most recently created first.

    • id (string, required): Unique identifier for the report. Pass it as id to the other /reports/{id} endpoints.
    • type (string, required): The kind of report, which decides the endpoints that work on it.

      • SlideDeck: a slide deck built in Rollstack. Every /reports/{id} endpoint works on it, except listReportSyncs and convertReport.
      • GoogleSlides, GoogleDocs, MicrosoftPowerPoint, MicrosoftWord: a file in Google Drive or OneDrive that Rollstack updates with its visualizations.
      • UploadedPPTXFile: a PowerPoint file uploaded to Rollstack, which it updates the same way.
      • Email: an email report, whose visualizations Rollstack sends in an email.

      On a report that isn't a SlideDeck, only getReport, updateReport, deleteReport, shareReport, unshareReport, getReportSchedules, updateReportSchedules, startReportRun, listReportRuns, getReportRun, cancelReportRun, listReportSyncs and the email endpoints (getReportEmailConfig, updateReportEmailConfig, listReportEmails, sendReportEmail, sendReportTestEmail) work, and convertReport on a GoogleSlides or MicrosoftPowerPoint report. The other /reports/{id} endpoints take SlideDeck reports only, as their id says, and return 400.

      One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.

    • name (string, required): Name of the report, as members see it in Rollstack. Change it with updateReport.
    • folderId (string or null, required): The folder the report is in, by its id in listFolders. null when the report is at the top level, outside any folder.
    • owner (object, required): The member who owns the report: whoever created it, unless ownership has since been transferred, in the app or with transferReportOwnership. Only the owner can delete the report.
      • id (number, required): The owner's user id, the same as their id in listMembers.
      • name (string, required): The owner's name, as shown in Rollstack.
      • email (string, required): The owner's email address. Rollstack emails this address when a scheduled run of the report fails, while notifyOnFailure is true.
    • permission (string or null, required): Your access to the report, as the user the API key belongs to. view lets you open and export it, and see its datasheets, runs, schedules and email setup. comment also lets you add, reply to and resolve comments on its slides. edit also lets you change it: rename or move it, chat with the slides agent about it, add datasheets and read their data, start runs, set its schedules and email, send its email, and share it. It's never null here, since the API only returns reports you can at least view. One of view, comment, edit.
    • timezone (string or null, required): The report's timezone, such as America/New_York. The slides agent uses it to tell today's date, and the report's emails show the time of its last successful update ({{last_updated_at}}) in it. On a report that updates a file, such as a Google Slides presentation, it's also the timezone of the file's date variables, unless the organization's timezone replaces it. Schedules don't use it: each has its own timezone. null when the report has none, in which case the slides agent uses UTC. Reports created with createReport start with the organization's timezone from getOrganization, if it has one.
    • notifyOnFailure (boolean, required): Whether Rollstack emails the report's owner when a scheduled run fails or some of its datasheets, or a file's visualizations, fail to refresh, copying everyone in notificationMailingList. Runs started in the app or with startReportRun never send this email. New reports start with true.
    • lastSyncedAt (string (date-time) or null, required): When the report's latest run ended, whatever its outcome. null if the report has never run.
    • lastSuccessfulUpdateAt (string (date-time) or null, required): When the report's latest fully successful run ended: one that refreshed every datasheet it ran on, or every visualization on a report that updates a file, with none failing. Runs with nothing to refresh don't count. The report's emails show this time as {{last_updated_at}}. null until the report has had such a run.
    • lastRunStatus (string or null, required): How the report's latest run ended. completed: it finished, even if some datasheets or visualizations failed to refresh or it had none to refresh; on a SlideDeck report, listReportDatasheets shows each datasheet's error. failed: it stopped on an error, or none of its datasheets or visualizations could be refreshed. cancelled: it was stopped before it finished, for example with cancelReportRun. null if the report has never run. running and timed_out never appear here: check running to see whether a run is in progress. One of running, completed, failed, cancelled, timed_out.
    • running (boolean, required): Whether a run of the report is in progress, whoever started it, such as you with startReportRun, a member in the app, or one of its schedules. While it's true, startReportRun returns that run instead of starting another.
    • appUrl (string (uri), required): Link that opens the report in Rollstack.
    • fileUrl (string or null, required): Link that opens the Google Slides, Google Docs, PowerPoint or Word file the report updates. null for a slide deck, an email report or an uploaded PowerPoint file, which have no file to open, and for a Microsoft file whose link Rollstack has not read yet.
    • createdAt (string (date-time), required): When the report was created. listReports returns the newest first.
    • updatedAt (string (date-time), required): When the report's details last changed, such as its name, folder or owner, or the outcome of its latest run.
  • nextCursor (string or null, required): Pass it as cursor to get the next page of reports. null when there are no more.