> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Get the code representation of a report (Beta)

> Retrieve a Sigma report as JSON or YAML code by calling the API Get a report endpoint with the reportId and includeContents=true.

This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.

This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see [Beta features](/docs/sigma-product-releases#beta-features).

You can retrieve a code representation of an existing report by calling the [Get a report](/reference/get-report) endpoint with the `reportId` for the report and the query parameter `includeContents=true`.

This document provides step-by-step instructions for using this endpoint to retrieve the representation of an existing report. For more information on working with reports programmatically, see [Manage reports as code](/docs/manage-reports-as-code).

The report code representation does not support all report features. Unsupported features are silently dropped when you make a request to the [Get a report](/reference/get-report) endpoint. If you use a representation from that endpoint to create or update another report from code, it does not include the dropped features, even if they were present in the original report.

## User requirements

The ability to retrieve a report code representation requires the following:

* You must have developer credentials for the Sigma API. For more information, see [Get started with the Sigma REST API](/reference/get-started-sigma-api).
* You must be the document owner or be granted at least **Can view** [access](/docs/folder-and-document-permissions) to the report.

## Generate API client credentials and an API access token

To start, you must generate credentials for the Sigma API. These credentials are used to retrieve an access token, which is required to make requests to the API.

For step-by-step instructions on generating developer credentials in Sigma and using them to authenticate to the Sigma API, see the instructions in [Generate client credentials](/reference/generate-client-credentials).

## Identify the report and retrieve the report ID

To retrieve the code representation of an existing report, you must know the unique `reportId` for that report. After you identify the report you want to retrieve the representation for, you can call the [List reports](/reference/list-reports) endpoint to retrieve the `reportId`:

1. Go to the Sigma **Home** page.

2. In the navigation menu, select **Documents**.

3. Click the ![](https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg) **Document type** filter and select **Reports**.

   The list of your reports appears.

4. Identify the report you want to retrieve the representation for by name, owner, or other details.

5. Make a GET request to the [List reports](/reference/list-reports) endpoint like the following:

   #### List reports request format

   ```shell
   curl --request GET \
       --url <base_url>/v2/reports \
       --header 'Authorization: Bearer <access_token>' \
       --header 'accept:application/json' \
       --header 'content-type: application/x-www-form-urlencoded'
   ```

   The response includes a list of reports in your organization, in the following format:

   #### List reports response format

   ```json
   {
     "entries": [
       {
         "reportId": "<reportId>",
         "reportUrlId": "<reportUrlId>",
         "createdBy": "<userId>",
         "updatedBy": "<userId>",
         "createdAt": "<timestamp>",
         "updatedAt": "<timestamp>",
         "name": "<reportName>",
         "url": "<reportUrl>",
         "path": "<folderPath>",
         "latestVersion": "<versionNumber>",
         "ownerId": "<userId>",
         "description": "<reportDescription>"
       },
       {
         "reportId": "<reportId>",
         "reportUrlId": "<reportUrlId>",
         "createdBy": "<userId>",
         "updatedBy": "<userId>",
         "createdAt": "<timestamp>",
         "updatedAt": "<timestamp>",
         "name": "<reportName>",
         "tags": [
           {
             "versionTagId": "<versionTagId>",
             "tagName": "<tagName>",
             "sourceVersion": "<versionNumber>",
             "taggedReportId": "<reportId>",
             "taggedAt": "<timestamp>"
           }
         ],
         "url": "<reportUrl>",
         "path": "<folderPath>",
         "latestVersion": "<versionNumber>",
         "ownerId": "<userId>"
       }
     ],
     "hasMore": <boolean>,
     "total": <number>,
     "nextPage": null
   }
   ```

6. Identify the report you want to retrieve the representation for, and copy the `reportId` to pass to the [Get a report](/reference/get-report) endpoint.

## Retrieve the representation

Using the `reportId`, make a GET request to the [Get a report](/reference/get-report) endpoint with the query parameter `includeContents=true`, using the following format:

#### Get a report representation request format

```shell
curl --request GET \
    --url '<base_url>/v2/reports/<reportId>?includeContents=true' \
    --header 'Authorization: Bearer <access_token>' \
    --header 'accept: application/json'
```

The response body contains the report metadata, the `documentVersion` the representation was read from, and the code representation of the report in the `contents` field.

To receive the response as YAML instead of JSON, add the query parameter `format=yaml` or the header `Accept: application/yaml`:

#### Get a report representation as YAML request format

```shell
curl --request GET \
    --url '<base_url>/v2/reports/<reportId>?includeContents=true&format=yaml' \
    --header 'Authorization: Bearer <access_token>'
```

To retrieve an earlier version of the representation, add the `documentVersion` query parameter. Without it, the endpoint returns the most recently published version. A `documentVersion` that does not exist returns a `404` error.

To see examples of report representations along with the instructions used to create them in the Sigma UI, see the [Report representation example library](/docs/report-representation-example-library).