---
title: "Create a new dashboard"
method: POST
path: "/v2/dashboards"
tags: ["Dashboards"]
---

# Create a new dashboard

`POST /v2/dashboards`

Creates a new dashboard from the provided definition.

## Request body

- DashboardUpdateRequest
  - `name` string, required — The dashboard name, which is displayed at the top of the dashboard and in lists. It does not need to be unique.
  - `definition` Dashboard, required — A JSON object describing a dashboard. A dashboard is an array of tiles. All tiles are of type 'chart', which query data and render a visualization, either a chart or table. Dashboards have 6 columns and as many rows as necessary to display their tiles.
    - `tiles` Tile[], required — The array of tiles. We currently support up to 102 tiles, which is 17 rows of 6x1 tiles.
      - `layout` object, required — Information about how the tile is placed on the dashboard. Examples: - a tile occupying the first half of the top row: `{ "position": { "col": 0, "row": 0 }, size: { "cols": 3, "rows": 1 } }` - a tile occupying the second half of the top row: `{ "position": { "col": 3, "row": 0 }, size: { "cols": 3, "rows": 1 } }`
        - `position` object, required — Position of the tile in the dashboard's grid. Numbering starts at 0, so a tile in the upper left of the dashboard will be at column 0, row 0.
          - `col` integer, required
          - `row` integer, required
        - `size` object, required — Number of columns and rows the tile occupies. A dashboard always has 6 columns, but has as many rows as needed to accommodate the given tiles.
          - `cols` integer, required
          - `rows` integer, required
      - `type` 'chart', required — The type of tile. Chart tiles must have type 'chart'.
      - `definition` union, required — The tile's definition, which consists of a query to fetch data and a visualization to render the data. Charts and tables expect certain query types to render properly. The documentation for the individual visualization types has more information.
        - ChartTileDefinition
          - `query` union, required
            - AdvancedQuery — A query targeting the API usage analytics datasource.
              - …
            - LLMQuery — A query targeting the LLM usage analytics datasource.
              - …
            - AgenticQuery — A query targeting the agentic usage analytics datasource.
              - …
            - PlatformQuery — A query targeting the platform usage analytics datasource.
              - …
          - `chart` union, required — The type of chart to render.
            - DonutChart — A chart that can display one-dimensional data in a hollow, segmented circle. To use this chart, ensure that the query includes only one dimension (not `time`).
              - …
            - TimeseriesChart — A chart that can render timeseries data -- data from a query that has `time` as a dimension -- as lines or bars. This type of chart can support: - One or more metrics: `{ metrics: ["response_latency_p99", "response_latency_p95"], dimensions: ["time"] }` - One metric plus one non-time dimension: `{ metrics: ["request_count"], dimensions: ["time", "gateway_service"] }` Either way, ensure that `time` is in the list of query dimensions.
              - …
            - BarChart — A chart that can display non-timeseries data as bars. This type of chart supports up to 2 dimensions (not `time`). To render a bar chart of timeseries data, use a `timeseries_bar` chart instead.
              - …
            - TopNChart — A chart that ranks dimension values by a metric and renders them as a table, showing the top results. This type of chart supports up to 3 dimensions.
              - …
            - SingleValueChart — A chart that can render a single number. This chart works with a single metric and no dimensions.
              - …
            - ChoroplethMapChart — A chart that displays data on a world map. Each region on the map is colored based on the metric value. This chart works only with the `api_usage` datasource and requires a single metric and a single dimension of `country_code`. No additional dimensions are supported.
              - …
        - TableChartTileDefinition
          - `query` PlatformTabularQuery, required — A query targeting tabular platform usage analytics data.
            - `datasource` 'platform_usage', required
            - `entity` string
            - `columns` string[]
            - `filters` PlatformFilter[] — A list of filters to apply to the query.
              - …
            - `cursor` string
            - `page_size` integer
          - `chart` TableChart, required — A table that displays tabular platform usage data.
            - `chart_title` string — The title of the chart, which is displayed in the tile's header.
            - `type` 'table', required
    - `preset_filters` AllFilterItems[] — An optional array of filters that are applied globally to all relevant tiles in the dashboard. Whether or not a preset filter applies to a tile depends on the filter's dimension. Some dimensions, like `control_plane`, are common to all datasources; other dimensions may only apply to one datasource.
      - `field` 'a2a_context_id' | 'a2a_error' | 'a2a_method' | 'a2a_task_id' | 'ai_plugin' | 'ai_provider' | 'ai_request_model' | 'ai_response_model' | 'api' | 'api_package' | 'api_product' | 'api_product_version' | 'application' | 'cache_status' | 'consumer' | 'control_plane' | 'control_plane_group' | 'country_code' | 'data_plane_node' | 'data_plane_node_version' | 'env' | 'gateway_service' | 'hostname' | 'llm_cache_status' | 'llm_embeddings_model' | 'llm_embeddings_provider' | 'mcp_error' | 'mcp_method' | 'mcp_session_id' | 'mcp_tool_name' | 'portal' | 'principal' | 'realm' | 'region' | 'response_source' | 'route' | 'status_code' | 'status_code_grouped' | 'team' | 'upstream_status_code' | 'upstream_status_code_grouped', required
      - `operator` 'in' | 'not_in' | 'empty' | 'not_empty', required
      - `value` unknown
  - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".

## Response `201`

The created dashboard, including generated fields.

- DashboardResponse
  - `name` string, required — The dashboard name, which is displayed at the top of the dashboard and in lists. It does not need to be unique.
  - `definition` Dashboard, required — A JSON object describing a dashboard. A dashboard is an array of tiles. All tiles are of type 'chart', which query data and render a visualization, either a chart or table. Dashboards have 6 columns and as many rows as necessary to display their tiles.
    - `tiles` Tile[], required — The array of tiles. We currently support up to 102 tiles, which is 17 rows of 6x1 tiles.
      - `layout` object, required — Information about how the tile is placed on the dashboard. Examples: - a tile occupying the first half of the top row: `{ "position": { "col": 0, "row": 0 }, size: { "cols": 3, "rows": 1 } }` - a tile occupying the second half of the top row: `{ "position": { "col": 3, "row": 0 }, size: { "cols": 3, "rows": 1 } }`
        - `position` object, required — Position of the tile in the dashboard's grid. Numbering starts at 0, so a tile in the upper left of the dashboard will be at column 0, row 0.
          - `col` integer, required
          - `row` integer, required
        - `size` object, required — Number of columns and rows the tile occupies. A dashboard always has 6 columns, but has as many rows as needed to accommodate the given tiles.
          - `cols` integer, required
          - `rows` integer, required
      - `type` 'chart', required — The type of tile. Chart tiles must have type 'chart'.
      - `definition` union, required — The tile's definition, which consists of a query to fetch data and a visualization to render the data. Charts and tables expect certain query types to render properly. The documentation for the individual visualization types has more information.
        - ChartTileDefinition
          - `query` union, required
            - AdvancedQuery — A query targeting the API usage analytics datasource.
              - …
            - LLMQuery — A query targeting the LLM usage analytics datasource.
              - …
            - AgenticQuery — A query targeting the agentic usage analytics datasource.
              - …
            - PlatformQuery — A query targeting the platform usage analytics datasource.
              - …
          - `chart` union, required — The type of chart to render.
            - DonutChart — A chart that can display one-dimensional data in a hollow, segmented circle. To use this chart, ensure that the query includes only one dimension (not `time`).
              - …
            - TimeseriesChart — A chart that can render timeseries data -- data from a query that has `time` as a dimension -- as lines or bars. This type of chart can support: - One or more metrics: `{ metrics: ["response_latency_p99", "response_latency_p95"], dimensions: ["time"] }` - One metric plus one non-time dimension: `{ metrics: ["request_count"], dimensions: ["time", "gateway_service"] }` Either way, ensure that `time` is in the list of query dimensions.
              - …
            - BarChart — A chart that can display non-timeseries data as bars. This type of chart supports up to 2 dimensions (not `time`). To render a bar chart of timeseries data, use a `timeseries_bar` chart instead.
              - …
            - TopNChart — A chart that ranks dimension values by a metric and renders them as a table, showing the top results. This type of chart supports up to 3 dimensions.
              - …
            - SingleValueChart — A chart that can render a single number. This chart works with a single metric and no dimensions.
              - …
            - ChoroplethMapChart — A chart that displays data on a world map. Each region on the map is colored based on the metric value. This chart works only with the `api_usage` datasource and requires a single metric and a single dimension of `country_code`. No additional dimensions are supported.
              - …
        - TableChartTileDefinition
          - `query` PlatformTabularQuery, required — A query targeting tabular platform usage analytics data.
            - `datasource` 'platform_usage', required
            - `entity` string
            - `columns` string[]
            - `filters` PlatformFilter[] — A list of filters to apply to the query.
              - …
            - `cursor` string
            - `page_size` integer
          - `chart` TableChart, required — A table that displays tabular platform usage data.
            - `chart_title` string — The title of the chart, which is displayed in the tile's header.
            - `type` 'table', required
    - `preset_filters` AllFilterItems[] — An optional array of filters that are applied globally to all relevant tiles in the dashboard. Whether or not a preset filter applies to a tile depends on the filter's dimension. Some dimensions, like `control_plane`, are common to all datasources; other dimensions may only apply to one datasource.
      - `field` 'a2a_context_id' | 'a2a_error' | 'a2a_method' | 'a2a_task_id' | 'ai_plugin' | 'ai_provider' | 'ai_request_model' | 'ai_response_model' | 'api' | 'api_package' | 'api_product' | 'api_product_version' | 'application' | 'cache_status' | 'consumer' | 'control_plane' | 'control_plane_group' | 'country_code' | 'data_plane_node' | 'data_plane_node_version' | 'env' | 'gateway_service' | 'hostname' | 'llm_cache_status' | 'llm_embeddings_model' | 'llm_embeddings_provider' | 'mcp_error' | 'mcp_method' | 'mcp_session_id' | 'mcp_tool_name' | 'portal' | 'principal' | 'realm' | 'region' | 'response_source' | 'route' | 'status_code' | 'status_code_grouped' | 'team' | 'upstream_status_code' | 'upstream_status_code_grouped', required
      - `operator` 'in' | 'not_in' | 'empty' | 'not_empty', required
      - `value` unknown
  - `labels` Labels — Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `id` string, uuid — Contains a unique identifier used for this resource.
  - `created_by` string, uuid — Contains a unique identifier used for this resource.
  - `created_at` string, date-time — An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time — An ISO-8601 timestamp representation of entity update date.

## Other responses

- `400` — Bad request; returned when the request payload was not valid.
- `401` — Unauthorized
- `403` — Forbidden

---

[API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/f920f418f552/schema)