---
title: "Convert a workbook to a report"
method: POST
path: "/v2/workbooks/{workbookId}/convertToReport"
tags: ["Workbooks"]
---

# Convert a workbook to a report

`POST /v2/workbooks/{workbookId}/convertToReport`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/workbooks/{workbookId}/convertToReport`
- Auth: HTTP bearer

This endpoint converts an existing workbook into a new report. When you convert a workbook, the existing workbook is not modified. Elements and functionality in the workbook that are not supported in reports are listed in a `warnings` array in the response. Unsupported workbook contents are either removed (not added to the new report) or, if supported contents depend on them, are added to a hidden page at the end of the report.
    See [Limitations and unsupported elements](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports#limitations-and-unsupported-elements).

    You can also convert a workbook to a report from the UI. See [Convert workbooks to reports](https://help.sigmacomputing.com/docs/convert-workbooks-to-reports).

### Usage notes
- Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint.
- The **name** parameter is required.
- Use **destinationFolderId** to choose where to save the report. If not provided, the report is saved to your **My Documents** folder.
- Use **pageIds** to convert only specific workbook pages. If not provided, the entire workbook is converted.
- Use **format** to set the page size and orientation. The default size is letter, and the default orientation is portrait.

## Path parameters

- `workbookId` string, required

## Request body

- object
  - `name` string, required: Name for the new report.
  - `destinationFolderId` string: ID of the folder in which to create the new report. Defaults to your "My Documents" folder.
  - `description` string: A description for the new report.
  - `pageIds` string[]: IDs of the workbook pages to convert. Defaults to the entire workbook.
  - `format` union: Page size and orientation for the report. Defaults to letter portrait.
    - V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat0: A standard page-size preset (letter, a4, legal, or a3).
      - `pageSize` 'letter' | 'a4' | 'legal' | 'a3', required: A standard page-size preset.
      - `layout` 'portrait' | 'landscape': Page orientation. Defaults to `portrait`.
    - V2WorkbooksWorkbookIdConvertToReportPostRequestBodyContentApplicationJsonSchemaFormat1: A custom page size, in pixels, inches, or centimeters.
      - `pageSize` 'custom', required: Use a custom page size.
      - `unit` 'pixels' | 'inches' | 'centimeters', required: Unit for the `width` and `height` values.
      - `width` number, double, required: Page width, in the given unit.
      - `height` number, double, required: Page height, in the given unit.

## Response `201`

The newly created report and conversion details.

- WorkbooksConvertWorkbookToReportResponse201: The newly created report and conversion details.
  - `convertedReport` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReport, required
    - `reportId` string, required: Unique identifier of the report.
    - `reportUrlId` string, required
    - `name` string, required
    - `url` string, required
    - `path` string, required
    - `latestVersion` number, double, required: The most recently published document version of the report.
    - `ownerId` string, required
    - `createdBy` string, required: The identifier of the user who created this object.
    - `updatedBy` string, required: The identifier of the user or process that last updated this object.
    - `createdAt` string, date-time, required: When the object was created.
    - `updatedAt` string, date-time, required: When the object was last updated.
    - `isArchived` boolean
    - `tags` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaConvertedReportTagsItems[]
      - `versionTagId` string, required: Unique identifier of the tag.
      - `tagName` string, required
      - `sourceVersion` number, double, required
      - `taggedAt` string, date-time, required
      - `taggedReportId` string, required: Unique identifier of the tagged report.
    - `description` string
  - `sourceWorkbook` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaSourceWorkbook, required
    - `workbookId` string, required: Unique identifier of the source workbook.
    - `name` string, required: Name of the source workbook.
    - `url` string, required: URL of the source workbook.
  - `warnings` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItems[], required: Warnings about content that could not be carried over to the report. May be empty.
    - `code` string, required: Machine-readable warning code, in kebab-case. Treat this as an open set and handle unknown codes gracefully.
    - `message` string, required: Human-readable explanation of the warning.
    - `details` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItems[]: Per-element details for this warning, when available.
      - `type` string, required: Element type, in kebab-case.
      - `count` number, double, required: Number of affected elements of this type.
      - `sourceElementIds` string[]: IDs of the affected elements in the source workbook.
      - `reportElementIds` string[]: IDs of the affected elements in the new report.
      - `parent` V2WorkbooksWorkbookIdConvertToReportPostResponsesContentApplicationJsonSchemaWarningsItemsDetailsItemsParent: The unsupported parent that caused this element to drop, if applicable.
        - `type` string, required: Unsupported parent type, in kebab-case (e.g. `sidebar-panel`, `repeater`, `modal`).
        - `id` string, required: ID of the unsupported parent in the source workbook.

---

[API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)