---
title: "Suggestions Agent"
method: POST
path: "/api/v0/suggestions"
tags: ["Agents"]
---

# Suggestions Agent

`POST /api/v0/suggestions`

Generate chart type and data preparation suggestions from a dataset. Send a GraphConfig and a prompt, receive suggested visualizations.

The response is a Server-Sent Events (SSE) stream with progress, complete, and error events.

## Request body

- SuggestionsRequest
  - `config` GraphConfig, required — The graph configuration object used to render charts. See [Graph Config Schema](/sdk/reference/graph-config) for the complete reference.
    - `type` 'line' | 'areaStacked' | 'bar' | 'groupedBar' | 'stackedBar' | '100StackedBar' | 'column' | 'groupedColumn' | 'stackedColumn' | '100StackedColumn' | 'combo' | 'pie' | 'donut' | 'funnel' | 'heatmap' | 'scatter' | 'bubble' | 'waterfall' | 'table' | 'mekko', required — The chart type
    - `data` object, required
      - `columns` object[]
        - `key` string
        - `label` string
      - `rows` object[]
  - `userPrompt` string, required — Natural language description of what to visualize
  - `metadata` Metadata — Optional tracking information for requests
    - `callId` string, required — Required when metadata is provided. Unique identifier for tracking and debugging.
    - `locale` 'EN_GB' | 'EN_US' | 'AR' | 'PT_PT' — Locale for responses
    - `effort` 'low' | 'medium' | 'high' — Preferred invocation tier; forwarded on the invocation (including nested agents). When omitted, it can be inferred from `storytellingEffort` or defaults to `medium`.
    - `storytellingEffort` 'none' | 'low' | 'medium' | 'high' — Deprecated. Prefer `effort`. When set without `effort`, the server derives `effort` for propagation. For chart generation, an explicit value still controls narrative richness when both `effort` and `storytellingEffort` are present (`storytellingEffort` wins for the chart).
  - `maxSuggestionCount` integer — Optional upper bound (1–4) communicated to the model for how many suggestions to aim for. The response is not truncated; the model may still return more items.

## Response `200`

SSE stream with progress and completion events

## Other responses

- `400` — Bad Request - Invalid request body
- `401` — Unauthorized - Invalid or missing API key

---

[API](https://skmtc.dev/graphy/apis/graphy-ai-agents-api.md) · [All operations](https://skmtc.dev/graphy/apis/graphy-ai-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/graphy/graphy-ai-agents-api/revisions/f181a68b6e0c/schema)