Skip to main content

list-reports 

dci list-reports [flags]

Returns a list of all Cloud Analytics reports that your account has access to. Reports are returned in reverse chronological order by default.

CLI default view

dci list-reports presents a curated table by default:

  • Columns: report name (from reportName; a clickable link to the report in the DoiT console in interactive terminals), owner, updated (UTC) (from updateTime), folder (folderId resolved to the folder name; blank for top-level reports), and labels (label names, comma-joined).
  • In interactive tables, updated (UTC) renders in your local timezone and is titled updated (local); machine formats, agent mode, and --utc keep UTC — see Timestamps and timezones.
  • Rows are sorted by last update, newest first.
  • --output json and explicit -C/--fields selections return the raw fields documented below.

Examples​

# Your most recently updated reports (one page of 50).
dci list-reports
# Reports owned by one user (server-side filter; keys are reportName, owner, type, updateTime, folderId, joined with `|`).
dci list-reports --filter "owner:[email protected]"
# Reports whose name contains a word, case-insensitively (combines with `--filter` using AND).
dci list-reports --name-contains sprint
# Every report as JSON, for scripts.
dci list-reports --all --output json
# Browse in the full-screen viewer; Enter prints the selected report's id.
dci list-reports -M interactive

Flags​

FlagTypeDefaultExampleDescription
--max-resultsinteger (int64)50The maximum number of results to return in a single page. Use the page tokens to iterate through the entire collection.
--page-tokenstringPage token, returned by a previous call, to request the next page of results
--filterstringreportName:This Month vs. LastAn expression for filtering the results. The syntax is key:[<value>]. Multiple filters can be connected using a pipe |. See Filters. Possible filter keys: reportName, owner, type, updateTime, folderId
--name-containsstringmonthly spendCase-insensitive substring match against the resource name. Combined with the "filter" parameter using AND semantics.
--min-creation-timestringMin value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created after or at this timestamp are returned.
--max-creation-timestringMax value for reports creation time, in milliseconds since the POSIX epoch. If set, only reports created before or at this timestamp are returned.

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

OK - The request succeeded.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
pageTokenstringPage token. It is used to request a specific page of the list results.
rowCountinteger (int64)The number of returned records.
reportsarray of object
reports[].idstringReport ID.
reports[].reportNamestringThe name of the report.
reports[].ownerstringEmail address of the report owner.
reports[].typestringOne of: "custom", "preset".
reports[].createTimeinteger (int64)The creation time of the report, in milliseconds since the epoch.
reports[].updateTimeinteger (int64)The time when this report was last updated, in milliseconds since the epoch.
reports[].urlUIstringThe URL of the report in DoiT console.
reports[].labelsarray of objectList of labels associated with the report.
reports[].labels[].idstringThe unique identifier of the label.
reports[].labels[].namestringThe name of the label.
Raw JSON schema
{
  "type": "object",
  "description": "List of reports.",
  "properties": {
    "pageToken": {
      "type": "string",
      "description": "Page token. It is used to request a specific page of the list results."
    },
    "rowCount": {
      "type": "integer",
      "description": "The number of returned records.",
      "format": "int64",
      "example": 5
    },
    "reports": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Report metadata and the console URL.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Report ID."
          },
          "reportName": {
            "type": "string",
            "description": "The name of the report."
          },
          "owner": {
            "type": "string",
            "description": "Email address of the report owner."
          },
          "type": {
            "type": "string",
            "enum": [
              "custom",
              "preset"
            ]
          },
          "createTime": {
            "type": "integer",
            "description": "The creation time of the report, in milliseconds since the epoch.",
            "format": "int64"
          },
          "updateTime": {
            "type": "integer",
            "description": "The time when this report was last updated, in milliseconds since the epoch.",
            "format": "int64"
          },
          "urlUI": {
            "type": "string",
            "description": "The URL of the report in DoiT console."
          },
          "labels": {
            "type": "array",
            "items": {
              "required": [
                "id",
                "name"
              ],
              "type": "object",
              "description": "Metadata for a label.",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The unique identifier of the label."
                },
                "name": {
                  "type": "string",
                  "description": "The name of the label."
                }
              }
            },
            "description": "List of labels associated with the report."
          }
        }
      }
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.

Aliases: listreports