> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List dashboard views for a pixel

> List the id, name, and sort order of every dashboard view on your pixel for one dashboard type, so you can find a view before reading, copying, or editing it.

**Required scope:** `dashboards:read`

Use this to look up a view's `id`. For example, find the view named "Weekly exec",
then pass its `id` to [Get a dashboard view](https://docs.upstackdata.com/api-reference/dashboards/get-a-dashboard-view.md)
or [Duplicate a dashboard view](https://docs.upstackdata.com/api-reference/dashboards/duplicate-a-dashboard-view.md).

* Each entry has only `id`, `name`, and `order`. Fetch the configuration with
  [Get a dashboard view](https://docs.upstackdata.com/api-reference/dashboards/get-a-dashboard-view.md).
* `type` defaults to `view`, the KPI dashboard. Pass `attribution_view` or `pnl_view`
  to list those dashboards instead. Any other value returns `400`.
* Every view of that type comes back in one response. There's no pagination.
* The list isn't sorted. Sort by `order` yourself if you need a stable order.
* Only views on the pixel in the `x-pixel-id` header are listed.

## Related

* [Create a dashboard view](https://docs.upstackdata.com/api-reference/dashboards/create-a-dashboard-view.md) from a full configuration.
* [Build a dashboard from a measure list](https://docs.upstackdata.com/api-reference/dashboards/build-a-dashboard-from-a-measure-list-preset.md) for an auto-laid-out view.
* [`upstack dashboard view`](https://docs.upstackdata.com/cli/dashboard-view) manages views from the CLI.


## OpenAPI

````yaml /api-reference/openapi.yaml get /accounts/api/dashboard/views
openapi: 3.1.0
info:
  title: Upstack Data API
  version: '1.0'
  description: >
    Programmatic access to your Upstack Data pixel — analytics queries, the

    measures/dimensions catalog, and dashboard view management.


    All requests authenticate with two headers:


    - `x-api-key`: your Upstack API key (mint one at **Settings → API Keys** in
    the dashboard).

    - `x-pixel-id`: the pixel id the request targets. One key is scoped to one
    pixel.
servers:
  - url: https://api.upstackdata.com
    description: Production
security:
  - apiKey: []
    pixelId: []
tags:
  - name: Analytics
    description: >
      Run measure queries, attribution queries, cohort analyses, and ad-platform
      entity

      listings against your pixel's orders, events, and ad spend. Every query
      endpoint

      takes the same `filters` tree. [List filter
      fields](/api-reference/catalog/list-filter-fields)

      tells you which fields each endpoint accepts.
  - name: Catalog
    description: >
      Look up the ids the query and dashboard endpoints accept: the built-in
      measures, and

      the filter fields with the operators and endpoints each one supports.
  - name: Dashboards
    description: >
      Create, read, copy, update, and delete the dashboard views shown in the
      Upstack web app.

      A view belongs to the pixel in the `x-pixel-id` header, and a key can only
      see its own

      pixel's views.
  - name: Account
    description: >
      Read the account that owns the API key, rename it, and read or replace its
      order

      settings: whether pending and voided orders count, how refunds are dated,
      and which

      orders are excluded from reporting.
  - name: Costs
    description: >
      Read and update cost settings: product defaults, the shipping method, and
      cost lines

      for order fees, payment processing fees, shipping profiles, variable
      costs, and

      recurring expenses. Changes to costs that apply per order recalculate the
      past orders

      they affect, the same as an edit in the web app.
  - name: Products
    description: >
      Search the product variants synced from Shopify and manage per-variant
      costs: manual

      COG lines with effective dates, and handling fees.
  - name: Events
    description: >-
      Upstack Conversion API (CAPI) — send server-side tracking events from your
      backend.
paths:
  /accounts/api/dashboard/views:
    get:
      tags:
        - Dashboards
      summary: List dashboard views
      description: >-
        List the id, name, and sort order of every dashboard view on your pixel
        for one dashboard type, so you can find a view before reading, copying,
        or editing it.
      operationId: listDashboardViews
      parameters:
        - name: type
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/DashboardViewType'
          description: Which dashboard's views to list. Defaults to `view`.
      responses:
        '200':
          description: List of view summaries.
          content:
            application/json:
              schema:
                type: object
                required:
                  - dashboardViews
                properties:
                  dashboardViews:
                    type: array
                    description: Every view of the requested type, unsorted.
                    items:
                      $ref: '#/components/schemas/DashboardViewSummary'
              examples:
                kpiViews:
                  summary: Three KPI dashboard views
                  value:
                    dashboardViews:
                      - id: 01K7B4C6D8E0F2G4H6J8K0M2N4
                        name: Weekly exec
                        order: 1
                      - id: 01K7A2Q9X3M4N5P6R7S8T9V0WZ
                        name: Summary
                        order: 0
                      - id: 01K7C9D1E3F5G7H9J1K3M5N7P9
                        name: NC + Meta Pulse
                        order: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    DashboardViewType:
      type: string
      enum:
        - view
        - attribution_view
        - pnl_view
      description: |
        Type of dashboard view.
        - `view`: the regular KPI dashboard.
        - `attribution_view`: the attribution dashboard.
        - `pnl_view`: the P&L dashboard.
    DashboardViewSummary:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: >-
            The view id. Pass it to [Get a dashboard
            view](/api-reference/dashboards/get-a-dashboard-view) for the full
            configuration.
        name:
          type: string
          description: Display name.
        order:
          type: integer
          description: Sort position. May be absent on older views.
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Human-readable error message.
        errors:
          type: array
          description: Per-field validation errors (present on 400 responses).
          items:
            type: object
            properties:
              message:
                type: string
              key:
                type: string
              path:
                type: array
                items:
                  type: string
  responses:
    BadRequest:
      description: Validation error. Includes an `errors` array with per-field detail.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: >
        The `x-api-key` or `x-pixel-id` header is missing. The request is
        rejected

        before it reaches the API, and the body is `{"message":
        "Unauthorized"}`.

        A key that is present but not accepted returns `403`, not `401`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >
        The key was rejected, or it is valid but not allowed to do this. Either:


        - the key is unknown, revoked, or expired, or the pixel is inactive —
        the body is
          `{"Message": "User is not authorized to access this resource with an explicit deny
          in an identity-based policy"}` (note the capital `M`);
        - the key doesn't carry the scope this endpoint needs, or the body
        `pixelId` doesn't
          match the `x-pixel-id` header — the body is `{"message": "…"}` as described below.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Upstack API key. Starts with `upstack_`.
    pixelId:
      type: apiKey
      in: header
      name: x-pixel-id
      description: The pixel id the request targets.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.