---
title: "Generate KB visualization plan"
method: POST
path: "/api/v0/knowledge-bases/{kb_id}/viz-plan"
tags: ["Knowledge Bases"]
---

# Generate KB visualization plan

`POST /api/v0/knowledge-bases/{kb_id}/viz-plan`

## Request

- Base URL: `https://api.outerport.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.outerport.com/api/v0/knowledge-bases/{kb_id}/viz-plan`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/outerport/apis/outerport-api/docs/api/v0/knowledge-bases/:kb_id/viz-plan/post.ts> (a function with typed inputs; its response is checked against the schema)

Ask a model which fields of the active schema are worth charting, and how, from the schema and a sample of the extraction records.

## Path parameters

- `kb_id` string, uuid, required

## Request body

- GenerateVizPlanRequest
  - `user_hint` string: Optional guidance for the LLM when choosing visualizations.
  - `sample_size` integer: Records shown to the model as examples of the data.
  - `max_distinct_values` integer: A string field with at most this many distinct values is listed to the model value by value, so it can chart it and spot aliases.
  - `max_tokens` integer: Output budget of the planning call.
  - `reasoning` string, nullable: Reasoning depth asked of the model; a depth the user saved for kb_viz_plan_model outranks it.

## Response `200`

Successful Response

- VizPlan
  - `summary_metric_field` string, nullable
  - `charts` VizChart[]
    - `field` string, required
    - `chart_type` 'donut' | 'bar' | 'grouped_bar' | 'rate' | 'numeric_by_field' | 'metric', required
    - `label` string, required
    - `group_by` string, nullable
    - `filter_field` string, nullable
    - `filter_values` string[], nullable
    - `numeric_field` string, nullable
    - `time_from_field` string, nullable
    - `time_to_field` string, nullable
    - `time_unit` 'seconds' | 'minutes' | 'hours' | 'days', nullable
    - `aggregation` 'mean' | 'median' | 'min' | 'max' | 'sum' | 'p95', nullable
    - `unit_label` string, nullable
    - `reason` string, nullable
  - `value_aliases` object
  - `rationale` string, nullable
  - `sample_size` integer
  - `record_count` integer
  - `results` union[]: Each chart counted over every record with the aliases applied, by position in `charts`; null for a chart no record holds data for.
    - union
      - DistributionResult: Records per value of the chart's field, most first.
        - `kind` 'distribution'
        - `total` integer, required
        - `buckets` Bucket[], required
          - `label` string, nullable, required
          - `count` integer, required
      - GroupedResult: Records per value of the chart's field, split by ``group_by``; rows most first.
        - `kind` 'grouped'
        - `total` integer, required
        - `rows` GroupedRow[], required
          - `label` string, required
          - `total` integer, required
          - `segments` Bucket[], required
            - `label` string, nullable, required
            - `count` integer, required
        - `segment_keys` string[], required
      - RateResult: Per value of the chart's field, the share of records whose ``filter_field`` is a ``filter_values`` value, highest first.
        - `kind` 'rate'
        - `total` integer, required
        - `rows` RateRow[], required
          - `label` string, required
          - `matching` integer, required
          - `total` integer, required
          - `rate` number, required
      - NumericResult: Per value of the chart's field, the ``aggregation`` of a number each record holds, highest first.
        - `kind` 'numeric'
        - `aggregation` 'mean' | 'median' | 'min' | 'max' | 'sum' | 'p95', required
        - `unit` string, required
        - `rows` NumericRow[], required
          - `label` string, required
          - `value` number, required
          - `count` integer, required
      - MetricResult: One figure over every record. ``count``: records whose ``filter_field`` is a ``filter_values`` value, of ``denominator`` records. ``ratio``: that count over the ``denominator`` records holding the field. ``numeric`` / ``duration``: the ``aggregation`` over the ``denominator`` records holding a number.
        - `kind` 'metric'
        - `metric` 'count' | 'ratio' | 'numeric' | 'duration', required
        - `value` number, required
        - `unit` string, required
        - `denominator` integer, required
        - `matching` integer, nullable
        - `aggregation` 'mean' | 'median' | 'min' | 'max' | 'sum' | 'p95', nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-09** `ecd5b922e78a`: 1 info
  - added the optional property `results` to the response with the `200` status
- **2026-10-13** `7f81908bcdfe`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/outerport/apis/outerport-api/changes/api/v0/knowledge-bases/:kb_id/viz-plan/post.md)

---

[API](https://skmtc.dev/outerport/apis/outerport-api.md) - [All operations](https://skmtc.dev/outerport/apis/outerport-api/llms.txt) - [OpenAPI document](https://skmtc.dev/outerport/apis/outerport-api/revisions/08b5bf6f7f18?raw)