DashboardUsageRankingResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/foundational/json-schema/foundational-dashboard-usage-ranking-response-schema.json",
  "title": "DashboardUsageRankingResponse",
  "description": "Org-wide dashboard ranking by recorded usage.\n\nRanks only dashboards that have recorded usage; dashboards with no usage\ndata are excluded from ``ranked`` and counted in ``excluded_no_data_count``\n(absence of tracking does not imply low usage). Usage covers a short trailing\nlookback only, so \"no usage data\" never means \"not viewed for N days\" beyond it.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/foundational-openapi.json#/components/schemas/DashboardUsageRankingResponse",
  "properties": {
    "ranked": {
      "items": {
        "$ref": "#/$defs/DashboardUsageRankingItem"
      },
      "type": "array",
      "title": "Ranked",
      "description": "Dashboards with recorded usage, ordered by the requested direction. With a last-view filter, also dashboards with no view in the lookback that a BI usage extraction covers (see ``last_view_basis``)"
    },
    "excludedNoDataCount": {
      "type": "integer",
      "title": "Excludednodatacount",
      "description": "Number of dashboards excluded for having no recorded usage: no view was recorded within the ~32-day usage lookback window, or usage is not tracked for them. This is not 'never viewed' and not 'not viewed in N days' for any N beyond the lookback; such a dashboard may have been viewed before the window or may be untracked. With a last-view filter, dashboards listed with a ``last_view_basis`` are not counted here."
    },
    "totalDashboards": {
      "type": "integer",
      "title": "Totaldashboards",
      "description": "Total dashboards in the org snapshot"
    },
    "listedNoViewCount": {
      "type": "integer",
      "title": "Listednoviewcount",
      "description": "With a last-view filter, how many listed dashboards had no view in the lookback: their BI tool's usage extraction covered them, and ``last_view_basis`` says how their last view is known. Always 0 without a filter.",
      "default": 0
    },
    "totalRanked": {
      "type": "integer",
      "title": "Totalranked",
      "description": "Total dashboards in ``ranked`` across every page of the ranking (with a last-view filter, only those that match it). Compare the length of ``ranked`` with this value to report how many of the total this page covers.",
      "default": 0
    },
    "lookbackStart": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lookbackstart",
      "description": "Earliest time the usage data can cover: views before it are not recorded here. Actual coverage may start later (e.g. a recently connected BI tool)."
    },
    "dataAsOf": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Dataasof",
      "description": "When the usage data was computed; views after it are not counted yet"
    },
    "lastViewedBefore": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Lastviewedbefore",
      "description": "The last-view cutoff applied, when filtered: ``ranked`` holds only dashboards whose most recent recorded view is before it. Untracked dashboards, and those the data cannot place before or after it, are never listed, only counted."
    },
    "truncated": {
      "type": "boolean",
      "title": "Truncated",
      "description": "True when ranked dashboards remain beyond this page — the returned list is partial. Fetch the remaining pages with ``page_token`` before presenting the ranking as complete.",
      "default": false
    },
    "pageToken": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Pagetoken",
      "description": "A token to fetch the next page of the ranking; absent on the last page"
    },
    "preparing": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Preparing",
      "description": "True when the ranking has not been precomputed for this org yet and is being prepared (the nightly scan has not run for it). When set, the other fields are placeholders and the ranking is not yet available — check back shortly."
    }
  },
  "type": "object",
  "required": [
    "ranked",
    "excludedNoDataCount",
    "totalDashboards"
  ],
  "$defs": {
    "DashboardUsageRankingItem": {
      "properties": {
        "id": {
          "type": "string",
          "title": "Id",
          "description": "The dashboard entity id"
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name",
          "description": "The dashboard name"
        },
        "monthlyViewCount": {
          "type": "integer",
          "title": "Monthlyviewcount",
          "description": "Recorded views over the trailing ~32-day usage lookback window"
        },
        "lastViewTime": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time"
            },
            {
              "type": "null"
            }
          ],
          "title": "Lastviewtime",
          "description": "Most recent recorded view time"
        },
        "lastViewBasis": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "all_time",
                "never_viewed",
                "none_in_lookback"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Lastviewbasis",
          "description": "Set only on a filtered ranking's rows with no view in the lookback (``monthly_view_count`` 0), from a BI tool whose usage extraction covered the dashboard: ``all_time`` -- ``last_view_time`` is the all-time last view the BI tool reports; ``never_viewed`` -- the BI tool reports no view ever; ``none_in_lookback`` -- no view since the lookback start, earlier views unknown. Unset on rows viewed within the lookback."
        }
      },
      "type": "object",
      "required": [
        "id",
        "monthlyViewCount"
      ],
      "title": "DashboardUsageRankingItem"
    }
  }
}