Reports API

The Reports v2 API lets you manage automated dashboard reports that are organized into folders. Every report belongs to a folder; if you do not specify one, the report is placed in the default folder.

These endpoints are served under the /api/v2/{org_id}/reports prefix and identify reports by their report_id (a KSUID). Folder placement is controlled with the folder query parameter. In OpenObserve Enterprise, this parameter is also used for RBAC permission checks and should be sent on every request that targets a report (see Permissions).

All requests require an authorization header. See the API Reference for how to build the HTTP basic-auth header.

Permissions

Report access is scoped by folder. In RBAC, permissions are evaluated against the rfolder (report folder) resource for the folder a report lives in, rather than against individual reports. To list, view, or modify reports in a folder, a user must hold the corresponding permission on that report folder.

Enterprise: pass the folder parameter for RBAC. In OpenObserve Enterprise, the permission check is evaluated against the report's folder (rfolder). For any request that targets a specific report (create, get, update, delete, enable, and trigger), include the folder query parameter set to the report's folder ID so the check resolves against the correct folder. Omitting it can cause the request to be denied or evaluated against the wrong folder. In Open Source (no RBAC), folder is optional and defaults to default.

Endpoints

Common path parameters

List Reports

Lists reports for the organization. Use the query parameters to scope the result to a folder or a specific dashboard.

Endpoint

GET /api/v2/{org_id}/reports

Query parameters

Example request

GET /api/v2/default/reports?folder=f_2abcDEF

Response

[
  {
    "report_id": "2cP9kZ7yQx1rT3wVnLm0",
    "name": "weekly-overview",
    "title": "Weekly Overview",
    "folder_id": "f_2abcDEF",
    "dashboards": ["3hQ8..."],
    "frequency": {
      "type": "weeks",
      "interval": 1,
      "cron": "",
      "align_time": false
    },
    "enabled": true,
    "owner": "admin@example.com",
    "last_triggered_at": 1717400000000000
  }
]

Create Report

Creates a new report in the folder named by the folder query parameter, or in the default folder when omitted.

Endpoint

POST /api/v2/{org_id}/reports

Query parameters

Request Body

Use the Report schema. The org_id, dashboards, and destinations fields are required.

{
  "name": "weekly-overview",
  "title": "Weekly Overview",
  "org_id": "default",
  "description": "Weekly summary delivered every Monday",
  "message": "Please find the weekly overview attached.",
  "enabled": true,
  "frequency": {
    "type": "weeks",
    "interval": 1,
    "cron": "",
    "align_time": false
  },
  "start": 1717400000000000,
  "timezone": "UTC",
  "timezoneOffset": 0,
  "dashboards": [
    {
      "dashboard": "3hQ8...",
      "folder": "default",
      "tabs": ["default"],
      "variables": [],
      "timerange": {
        "type": "relative",
        "period": "1w",
        "from": 0,
        "to": 0
      }
    }
  ],
  "destinations": [
    { "email": "team@example.com" }
  ]
}

Field reference (Report)

Response

{
  "code": 200,
  "message": "Report saved"
}

Get Report

Returns a single report by ID.

Endpoint

GET /api/v2/{org_id}/reports/{report_id}

Query parameters

Response

Returns the full Report object. Returns 404 Not Found if the report does not exist.

Update Report

Updates an existing report. Provide the full Report body. To move the report to a different folder in the same request, include the folder query parameter; when omitted, the report stays in its current folder.

Endpoint

PUT /api/v2/{org_id}/reports/{report_id}

Query parameters

Example request

PUT /api/v2/default/reports/2cP9kZ7yQx1rT3wVnLm0?folder=f_archive

Response

{
  "code": 200,
  "message": "Report updated"
}

Delete Report

Deletes a single report by ID.

Endpoint

DELETE /api/v2/{org_id}/reports/{report_id}

Query parameters

Response

{
  "code": 200,
  "message": "Report deleted"
}

Bulk Delete Reports

Deletes multiple reports by ID in a single request. Deletion is idempotent: IDs that do not exist are reported as successful.

Endpoint

DELETE /api/v2/{org_id}/reports/bulk

Request Body

{
  "ids": [
    "2cP9kZ7yQx1rT3wVnLm0",
    "2cQ0aB1cD2eF3gH4iJ5k"
  ]
}

Response

{
  "successful": ["2cP9kZ7yQx1rT3wVnLm0", "2cQ0aB1cD2eF3gH4iJ5k"],
  "unsuccessful": [],
  "err": null
}

Move Reports

Moves one or more reports to a destination folder.

Endpoint

PATCH /api/v2/{org_id}/reports/move

Request Body

{
  "report_ids": ["2cP9kZ7yQx1rT3wVnLm0"],
  "dst_folder_id": "f_archive"
}

Response

{
  "code": 200,
  "message": "Report moved"
}

Enable or Disable a Report

Enables or disables a report's schedule.

Endpoint

PATCH /api/v2/{org_id}/reports/{report_id}/enable

Query parameters

Example request

PATCH /api/v2/default/reports/2cP9kZ7yQx1rT3wVnLm0/enable?value=true

Response

{
  "enabled": true
}

Trigger a Report

Manually triggers report generation and delivery, independent of its schedule.

Endpoint

PUT /api/v2/{org_id}/reports/{report_id}/trigger

Query parameters

Response

{
  "code": 200,
  "message": "Report triggered"
}

Next steps

• API Reference: Overview of the OpenObserve REST API and how to build the authorization header.
• Reports: Create and schedule dashboard reports from the UI.
• Stream Settings API: Manage stream-level settings via the API.

Need some help?

• Join our Community Slack
• Or Contact support