---
title: "Create Dashboard"
method: POST
path: "/v1/dashboards"
tags: ["Dashboards"]
---

# Create Dashboard

`POST /v1/dashboards`

Creates a dashboard, optionally with starter widget configurations, and returns the id of the created dashboard. Use the dashboard detail endpoint for its full configuration, or a query endpoint for computed widget data.

## Request body

- CreateDashboardRequest — The dashboard to create, optionally with starter widgets.
  - `name` string, required — The dashboard's name.
  - `description` string, nullable — An optional description of the dashboard.
  - `private` boolean — Whether the dashboard is private. Defaults to false.
  - `widgets` DashboardWidgetInput[] — Optional starter widgets to create alongside the dashboard.
    - `name` string, required — The widget's name.
    - `description` string, nullable — An optional description of the widget.
    - `type` 'LINE' | 'AREA' | 'BAR' | 'STACKED_BAR' | 'TABLE' | 'BIG_NUMBER' — The visualization type of a widget.
    - `unit` 'COUNT' | 'PERCENT' | 'SCORE' | 'SECONDS' | 'USD' | 'MILLISECONDS' — The unit a widget's values are measured in.
    - `mode` 'TIME_SERIES' | 'DIMENSION_SERIES' — How a widget aggregates its lines. `TIME_SERIES` plots each configured line over time; `DIMENSION_SERIES` takes a single metric and splits it into one series per value of the widget's dimension. This is the widget's saved configuration — it does not by itself describe the shape of a query response (use `kind` on the query result for that).
    - `bucketMode` 'SERIES' | 'RANGE' — How a widget's data is bucketed over the query time range. `SERIES` splits the range into one bucket per `granularity` interval (a time series); `RANGE` aggregates the whole range into a single bucket (one total, as used by BIG_NUMBER widgets). Defaults to `SERIES` when omitted.
    - `dimension` 'project' | 'trace_name' | 'span_name' | 'model' | 'type' | 'thread_id' | 'test_case_id' | 'test_run_id' | 'end_user' | 'source' | 'annotator' | 'name' | 'error' | 'prompt_alias' | 'tag' | 'label' | 'evaluation_model' | 'prompt_version' | 'prompt_label' | 'prompt_commit_hash' | 'metadata' | 'classifier' — The dimension a widget breaks down by when mode is DIMENSION_SERIES.
    - `topK` DashboardTopK — Limits a dimension breakdown to the top K series.
      - `limit` integer — Maximum number of series to return. Defaults to 10.
      - `orderBy` 'count' | 'avg_latency' | 'p50_latency' | 'p90_latency' | 'p99_latency' | 'error_rate' | 'pass_rate' | 'failure_rate' | 'input_cost' | 'output_cost' | 'total_cost' | 'avg_cost' | 'input_tokens' | 'output_tokens' | 'total_tokens' | 'count_distinct_endUserId' | 'count_distinct_threadId' | 'count_distinct_model' | 'count_distinct_projectId' | 'count_distinct_error' | 'count_distinct_metadata' | 'error_count' | 'avg_score' | 'stddev_score' | 'avg_rating' | 'created_at' | 'start_time' | 'dimension' — The metric or column to order topK results by.
      - `direction` 'asc' | 'desc' — The sort direction for topK results.
    - `startTime` string, date-time, nullable — The start of the widget's custom time range, if set.
    - `endTime` string, date-time, nullable — The end of the widget's custom time range, if set.
    - `layout` DashboardLayout — A widget's position on the dashboard grid.
      - `x` number — The widget's left edge as a column index on the 12-column grid.
      - `y` number — The widget's top edge as a row index on the grid.
      - `w` number — The widget's width in grid columns.
      - `h` number — The widget's height in grid rows.
    - `lines` DashboardLineInput[], nullable — The series to show in the widget.
      - `name` string, required — The line's name.
      - `color` 'AMBER' | 'VIOLET' | 'EMERALD' | 'BLUE' | 'PINK' | 'CYAN' | 'ROSE' | 'LIME' | 'TEAL' | 'ORANGE' — The color of a line. If omitted or unrecognized, a color is auto-assigned from the palette.
      - `dataModel` 'TRACE' | 'SPAN' | 'LLM_SPAN' | 'AGENT_SPAN' | 'RETRIEVER_SPAN' | 'TOOL_SPAN' | 'CUSTOM_SPAN' | 'THREAD' | 'END_USER' | 'METRIC_DATA' | 'ANNOTATION' — The entity a line aggregates over.
      - `aggregation` 'COUNT' | 'ERROR_RATE' | 'PASS_RATE' | 'UNIQUE_END_USERS' | 'UNIQUE_THREADS' | 'UNIQUE_USERS' | 'UNIQUE_METADATA_VALUES' | 'AVG_LATENCY' | 'P50_LATENCY' | 'P90_LATENCY' | 'P99_LATENCY' | 'TOTAL_COST' | 'AVG_COST' | 'INPUT_COST' | 'OUTPUT_COST' | 'AVG_COST_PER_USER' | 'INPUT_TOKENS' | 'OUTPUT_TOKENS' | 'TOTAL_TOKENS' | 'ERROR_COUNT' | 'NEW_USERS' | 'RETENTION' | 'AVG_SCORE' | 'FAILURE_RATE' | 'AVG_RATING' — The aggregation applied to a line. The set of valid values depends on the line's dataModel.
      - `filters` DashboardFilterSet — A set of filter groups combined by a top-level operator.
        - `operator` 'AND' | 'OR', required — How filters or groups are combined.
        - `groups` DashboardFilterGroup[], required — The filter groups.
          - `operator` 'AND' | 'OR', required — How filters or groups are combined.
          - `filters` DashboardFilterRow[], required — The filter rows in this group.
            - `category` string, required — The property a filter row matches on (e.g. "Name", "User Id", "Model", "Metadata"). The set of valid values depends on the line's dataModel.
            - `condition` 'Is' | 'Is not' | 'Is equal to' | 'Does not equal' | 'Is less than' | 'Is equal or less than' | 'Is greater than' | 'Is equal or greater than' | 'Has' | 'Has not' | 'Contains' | 'Contains only' | 'Does not contain' | 'Has increased by more than' | 'Has increased by less than' | 'Has decreased by more than' | 'Has decreased by less than' | 'Has changed from', required — The comparison a filter row applies. Valid conditions depend on the category.
            - `value` union, required — The value to match against.
              - …
            - `key` string — The property key. Auto-populated from category when omitted; required for Metadata, Metric, and Classifier filters.
      - `extraQueryParams` DashboardLineExtraQueryParams, nullable — Advanced, per-line query parameters. Which keys take effect depends on the line's `dataModel`, and unrecognized keys are ignored. All values are strings. Most lines leave this `null`.
        - `spanType` 'LLM' | 'AGENT' | 'RETRIEVER' | 'TOOL' | 'CUSTOM' — For a `SPAN` line, restricts aggregation to a single span type. Not needed for the typed span models (`LLM_SPAN`, `AGENT_SPAN`, `RETRIEVER_SPAN`, `TOOL_SPAN`, `CUSTOM_SPAN`), which already imply their span type.
        - `metricMetadataKey` string — For span (`SPAN`, `LLM_SPAN`, `AGENT_SPAN`, `RETRIEVER_SPAN`, `TOOL_SPAN`, `CUSTOM_SPAN`), `TRACE`, and `THREAD` lines, the metadata field key whose numeric value is aggregated.
        - `category` 'SINGLE_TURN' | 'MULTI_TURN' | 'TEST_RUN' | 'TRACE' | 'SPAN' | 'LLM_SPAN' | 'AGENT_SPAN' | 'RETRIEVER_SPAN' | 'TOOL_SPAN' | 'CUSTOM_SPAN' | 'THREAD' — For a `METRIC_DATA` line, the entity category the metric is attached to.
        - `metricName` string — For a `METRIC_DATA` line, the name of the metric to aggregate.
        - `dataType` 'Traces' | 'Spans' | 'Threads' — For an `ANNOTATION` line, which annotated entity type to aggregate over.
        - `source` 'User' | 'Reviewer' — For an `ANNOTATION` line, whether to aggregate annotations left by end users or by reviewers.

## Response `200`

The id of the created dashboard.

- DashboardIdResponse
  - `success` boolean, required — Indicates if the request was successful.
  - `data` object, required — The id of the affected dashboard or widget.
    - `id` string, required — The id of the affected dashboard or widget.
  - `deprecated` boolean, required — Indicates if this endpoint is deprecated.

---

[API](https://skmtc.net/confident-ai/apis/confident-ai-metrics-api.md) · [All operations](https://skmtc.net/confident-ai/apis/confident-ai-metrics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/confident-ai/confident-ai-metrics-api/versions/95cdde71b65e/schema)