studio.reports.update

Update a Data Studio report.

Facts


Method	`POST https://api.getdx.com/studio.reports.update`
Required scope	`studio:reports:write`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`id`	`Text`	Public ID of the report.

Optional arguments

Name	Type	Description
`name`	`Text`	The report name. Blank values are ignored.
`description`	`Text`	Description of the report.
`markdown_notes`	`Text`	Markdown notes to give details about the report.
`view_access_type`	`Text`	Who can view the report. Valid values are `owner_and_direct_url_only`, `everyone`, and `specific_users`.
`edit_access_type`	`Text`	Who can edit the report. Valid values are `read_only`, `everyone`, and `specific_users`.
`viewer_emails`	`Array<Text>`	List of users who can view the report. Include when `view_access_type` is `specific_users`, or when the existing report already uses `specific_users` view access.
`editor_emails`	`Array<Text>`	List of users who can edit the report. Include when `edit_access_type` is `specific_users`, or when the existing report already uses `specific_users` edit access.
`tiles`	`Array<Studio Report Tile>`	Replacement list of supported tiles on the report.

Usage info

Organization API keys can update any Data Studio report in the account.
Personal access tokens can update reports the token owner can edit.
If tiles is supplied, DX replaces the report’s supported public tiles with the supplied list.
Unsupported existing tiles, such as number tiles, are not returned by this API and are not replaced.
If tiles is omitted, existing tiles are left unchanged.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/studio.reports.update \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "id": "ou9lhoz888sa",
    "name": "Web Metrics",
    "description": "Main application web visit metrics",
    "markdown_notes": "## Objectives\n---\n* Provide high-level traffic metrics for marketing team\n* Surface for debugging reported web issues.",
    "view_access_type": "everyone",
    "edit_access_type": "read_only",
    "tiles": [
      {
        "title": "Median visit duration",
        "sql": "SELECT avg(duration) AS avg_duration, week_start FROM custom.web_visits;",
        "chart_type": "line",
        "chart_config": {
          "xAxis": "week_start",
          "yAxes": ["avg_duration"]
        }
      }
    ]
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "report": {
    "id": "ou9lhoz888sa",
    "name": "Web Metrics",
    "description": "Main application web visit metrics",
    "markdown_notes": "## Objectives\n---\n* Provide high-level traffic metrics for marketing team\n* Surface for debugging reported web issues.",
    "view_access_type": "everyone",
    "edit_access_type": "read_only",
    "url": "https://app.getdx.com/datacloud/studio/reports/OTEzNA",
    "tiles": [
      {
        "id": "MTE4e2",
        "title": "Median visit duration",
        "sql": "SELECT avg(duration) AS avg_duration, week_start FROM custom.web_visits;",
        "chart_type": "line",
        "chart_config": {
          "xAxis": "week_start",
          "yAxes": ["avg_duration"]
        }
      }
    ],
    "created_at": "2026-03-12T19:56:11Z",
    "updated_at": "2026-05-12T10:46:12Z"
  }
}

The report field is a Studio Report object.

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
`not_authed`	No authentication token provided, or Data Cloud is not available.
`invalid_auth`	Some aspect of authentication cannot be validated.
`not_authorized`	The bearer token does not include the required `studio:reports:write` scope, the personal access token owner cannot access Data Studio, or the token owner cannot edit the report.
`not_found`	No report with that ID exists in the current account.
`invalid_arguments`	One or more arguments are invalid.
`too_many_requests`	Too many requests were sent in a short period of time.