Visualize Data
Render a chart from a previously analysed dataset using a flexible chart spec. Returns Plotly JSON or a hosted PNG/SVG image URL.
/v1/visualize
curl -X POST "https://analytics.toolkitapi.io/v1/visualize" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "ds_abc123",
"chart_spec": {
"chart_type": "bar",
"x": "region",
"y": "revenue",
"aggregation": "sum",
"sort": {"by": "revenue", "direction": "desc"},
"limit": 20,
"title": "Revenue by Region",
"theme": "plotly_white",
"color_scheme": "D3",
"bar_mode": "group",
"width": 1200,
"height": 600
},
"output_format": "plotly_json"
}'
import httpx
resp = httpx.post(
"https://analytics.toolkitapi.io/v1/visualize",
json={
"dataset_id": "ds_abc123",
"chart_spec": {
"chart_type": "bar",
"x": "region",
"y": "revenue",
"aggregation": "sum",
"sort": {"by": "revenue", "direction": "desc"},
"limit": 20,
"title": "Revenue by Region",
"theme": "plotly_white",
"color_scheme": "D3",
"bar_mode": "group",
"width": 1200,
"height": 600
},
"output_format": "plotly_json"
},
)
print(resp.json())const resp = await fetch("https://analytics.toolkitapi.io/v1/visualize", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
"dataset_id": "ds_abc123",
"chart_spec": {
"chart_type": "bar",
"x": "region",
"y": "revenue",
"aggregation": "sum",
"sort": {"by": "revenue", "direction": "desc"},
"limit": 20,
"title": "Revenue by Region",
"theme": "plotly_white",
"color_scheme": "D3",
"bar_mode": "group",
"width": 1200,
"height": 600
},
"output_format": "plotly_json"
}),
});
const data = await resp.json();
console.log(data);# See curl example{
"plotly_json": {
"data": [
{
"type": "bar",
"x": ["North", "South", "East", "West"],
"y": [48200, 35100, 29400, 21800],
"name": "revenue"
}
],
"layout": {
"title": {"text": "Revenue by Region"},
"template": "plotly_white",
"width": 1200,
"height": 600
}
},
"image_url": null,
"meta": {
"request_id": "req_viz001",
"runtime_ms": 340.2,
"cache_hit": true,
"schema_fingerprint": "fp_abc123"
}
}Description
How to Use
1. Obtain a `dataset_id` from a prior `/v1/analyze` or `/v1/datasets/bundle` call. 2. Build a `chart_spec` describing the chart type, axes, aggregation, and styling. 3. `POST` to `/v1/visualize` with `output_format` set to `plotly_json`, `png`, or `svg`. 4. For `plotly_json`, pass the returned object directly to a Plotly renderer. 5. For `png` / `svg`, download or embed the `image_url` — it is a short-lived pre-signed URL.
About This Tool
The **Visualize** endpoint renders a chart from a previously analysed `dataset_id` using a declarative `chart_spec`. It validates the spec against the dataset schema before executing, so column-name typos or incompatible aggregations are caught with a descriptive 400 error rather than a silent empty chart.
By default the endpoint returns a Plotly JSON structure (`output_format: plotly_json`) that can be passed directly to `Plotly.react()` in any JavaScript front-end. For server-side pipelines or report generation, set `output_format` to `png` or `svg` to receive an authenticated object-storage URL pointing to the rendered image.
> **Tip for MCP / agent workflows:** Call `/v1/validate-chart` first with the same `dataset_id` and `chart_spec` to catch errors before incurring the cost of rendering. The validate endpoint is free of side effects and returns field-level error messages.
Why Use This Tool
- Front-end dashboards — embed the Plotly JSON in a React or Vue component with zero server infrastructure.
- Automated report generation — request a PNG and attach it to a nightly email or Slack message.
- AI agent workflows — let an LLM compose a `chart_spec` from a user question and call this endpoint to produce the chart.
- Data storytelling — chain analyze → visualize multiple times with different specs to compare slices of the same dataset.
Start using Visualize Data now
Get your free API key and make your first request in under a minute.