studio.reports.create

Create a Data Studio report.

Facts


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

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`name`	`Text`	The report name.

Optional arguments

Name	Type	Description
`owner_email`	`Text`	Email address of the report owner. Required when using an organization API key. Personal access tokens create reports owned by the token owner and cannot assign another owner.
`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`. Defaults to `owner_and_direct_url_only`.
`edit_access_type`	`Text`	Who can edit the report. Valid values are `read_only`, `everyone`, and `specific_users`. Defaults to `read_only`.
`viewer_emails`	`Array<Text>`	List of users who can view the report. Include when `view_access_type` is `specific_users`.
`editor_emails`	`Array<Text>`	List of users who can edit the report. Include when `edit_access_type` is `specific_users`.
`tiles`	`Array<Studio Report Tile>`	List of supported tiles on the report.

Usage info

Supported tile chart types are line, pie, stacked_bar, scatter, and table.
Tile SQL must be a valid read-only query.
If view_access_type is specific_users, viewer_emails must include at least one valid user email.
If edit_access_type is specific_users, editor_emails must include at least one valid user email.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/studio.reports.create \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "name": "Web Metrics",
    "owner_email": "owner@example.com",
    "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 a personal access token tried to assign another owner.
`invalid_arguments`	One or more arguments are invalid.
`too_many_requests`	Too many requests were sent in a short period of time.