> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Thin-Viz
export const CodingAgentCTA = ({description, href}) =>
{description} Building with a coding agent?{" "}
Give your agent the full reference →
;
Create interactive, embeddable cards from your own data using the Tako Thin-Viz API.
## Why Thin-Viz
* **Your data, Tako's rendering.** Post your own values and component configs; Tako returns a polished, interactive card — no charting library or frontend work on your side.
* **A full component gallery.** Timeseries, bar, pie, table, treemap, sankey, choropleth, heatmap, waterfall, and more — composed top to bottom in a single card.
* **Embed anywhere.** Every card comes back with an `embed_url` (interactive iframe) and an `image_url` (static image) for chat, dashboards, or docs.
## Creating a Card
Create a card by posting your component configurations. One API call, one card.
```bash theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Monthly Revenue",
"source": "Internal Analytics",
"components": [
{
"component_type": "generic_timeseries",
"config": {
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "2024-01", "y": 50000},
{"x": "2024-02", "y": 62000},
{"x": "2024-03", "y": 71000}
],
"units": "$"
}
],
"chart_type": "line",
"title": "Monthly Revenue"
}
}
]
}'
```
```bash theme={null}
pip install tako-sdk
```
```python theme={null}
import os
from tako import Configuration, CreateCardRequest, ComponentConfig
from tako.lib import Tako
config = Configuration()
config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
client = Tako(config)
card = client.create_card(CreateCardRequest(
title="Monthly Revenue",
source="Internal Analytics",
components=[
ComponentConfig(
component_type="generic_timeseries",
config={
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "2024-01", "y": 50000},
{"x": "2024-02", "y": 62000},
{"x": "2024-03", "y": 71000}
],
"units": "$"
}
],
"chart_type": "line",
"title": "Monthly Revenue"
},
),
],
))
print(card.embed_url)
```
Response:
```json theme={null}
{
"card_id": "abc123xyz",
"title": "Monthly Revenue",
"description": "",
"embed_url": "https://tako.com/embed/abc123xyz",
"image_url": "https://tako.com/api/v1/image/abc123xyz/",
"webpage_url": "https://tako.com/card/abc123xyz",
"card_type": "chart",
"visualization_data": { ... }
}
```
### Request Fields
| Field | Type | Required | Description |
| - | - | - | - |
| `components` | array | Yes | List of component configurations (see [Available Components](#available-components)) |
| `title` | string | No | Card title (falls back to header component title if not provided) |
| `description` | string | No | Card description |
| `source` | string | No | Data source attribution displayed in footer |
| `image_ttl_minutes` | integer | No | Minutes to keep a preview image available for download (1–1440). ZDR cards only. See [Preview Images for ZDR Cards](#preview-images-for-zdr-cards) |
## Embedding Your Card
Use the `embed_url` from the response in an iframe:
```html theme={null}
```
Add `?dark_mode=true` or `?dark_mode=false` to control the theme.
## Preview Images for ZDR Cards
Cards created with zero data retention (ZDR) don't normally support preview images because the visualization data isn't persisted. To get a downloadable image for a ZDR card, set `image_ttl_minutes` when creating the card:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Monthly Revenue",
"image_ttl_minutes": 60,
"components": [ ... ]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Monthly Revenue",
image_ttl_minutes=60,
components=[...], # see the examples below for full component configs
))
```
The response includes an `image_url` that renders a screenshot on demand. You can customize the image with query parameters:
| Parameter | Type | Description |
| - | - | - |
| `dark_mode` | boolean | `true` for dark theme, `false` for light |
| `width` | integer | Image width in pixels |
| `height` | integer | Image height in pixels |
| `hideFooter` | boolean | Hide the card footer |
```
https://tako.com/api/v1/image/abc123xyz/?dark_mode=true&width=800&height=600
```
After the TTL expires, the image endpoint returns `410 Gone`. The TTL must be between 1 and 1440 minutes (24 hours).
`image_ttl_minutes` is only supported for ZDR cards and is ignored for standard cards, which already have persistent preview images.
## Shared Config Options
Every component takes a `config` object whose shape depends on its `component_type`. Each example below lists its component's fields. Tako ignores unknown `config` fields without an error, so if an option has no effect, check its spelling.
Many components accept these optional fields:
| Field | Type | Description |
| - | - | - |
| `title` | string | Chart title. Most charts show it in the tooltip, not above the chart. For a visible title, add a `header` component. |
| `series_color_theme` | string | Color scheme: `"default"`, `"red_bad_green_good"` (green for positive values, red for negative), `"gray"`, `"divergent"`, `"sequential"`, `"categorical"`, or `"uniform"` (one color for every point). |
| `legend` | object | Legend settings: `show` (boolean, on by default for multi-series charts), `position` (`"top"` or `"bottom"`, default `"bottom"`), and `items`, a custom list of `label`, optional `value`, and optional `color` entries. |
### Color Overrides
Set `color` to a hex string (`#RGB` or `#RRGGBB`) to override a series color in both themes. Add `color_light_mode` or `color_dark_mode` to use a different color in one theme; they take precedence over `color`.
* Dataset-level colors work on `generic_timeseries`, `categorical_bar`, `data_table_chart`, and `scatter`.
* Per-point `color` works on `categorical_bar`, `data_table_chart`, and `choropleth` data points.
* Per-event `color` works on `timeline` events, in `#RRGGBB` form.
* Other components take their colors from `series_color_theme`. `bubble` datasets accept `color` fields but don't apply them yet.
## Example: Stock Card with Kicker Boxes
For financial data, use the `generic_timeseries` component with `show_kicker_boxes` enabled:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "AAPL vs GOOGL",
"source": "Market Data",
"components": [
{
"component_type": "generic_timeseries",
"config": {
"datasets": [
{
"label": "AAPL",
"kicker": "NASDAQ",
"data": [
{"x": "2024-01-01", "y": 185.50},
{"x": "2024-01-02", "y": 195.20}
],
"units": "$"
},
{
"label": "GOOGL",
"kicker": "NASDAQ",
"data": [
{"x": "2024-01-01", "y": 152.60},
{"x": "2024-01-02", "y": 150.10}
],
"units": "$"
}
],
"chart_type": "line",
"title": "Stock Price (USD)",
"show_kicker_boxes": true
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="AAPL vs GOOGL",
source="Market Data",
components=[
ComponentConfig(
component_type="generic_timeseries",
config={
"datasets": [
{
"label": "AAPL",
"kicker": "NASDAQ",
"data": [
{"x": "2024-01-01", "y": 185.50},
{"x": "2024-01-02", "y": 195.20}
],
"units": "$"
},
{
"label": "GOOGL",
"kicker": "NASDAQ",
"data": [
{"x": "2024-01-01", "y": 152.60},
{"x": "2024-01-02", "y": 150.10}
],
"units": "$"
}
],
"chart_type": "line",
"title": "Stock Price (USD)",
"show_kicker_boxes": True
},
),
],
))
```
When `show_kicker_boxes` is enabled, each dataset with a `kicker` field renders a stock box above the chart showing the exchange label, current value, and change.
### Timeseries Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | The series to plot. Provide this or `datasets_by_interval`, not both |
| `datasets_by_interval` | object | — | Maps ISO 8601 durations (for example, `"PT5M"` or `"P1D"`) to arrays of datasets. Tako builds the date picker from the intervals |
| `chart_type` | `"line"` \| `"bar"` \| `"scatter"` | `"line"` | Default chart type. A dataset's `type` overrides it |
| `title` | string | — | Tooltip title |
| `default_date_picker_option` | string | First option | Initial date range as an ISO period, such as `"P1Y"`, `"P3M"`, or `"YTD"`. Falls back to the first option when the value isn't available |
| `exclude_date_picker_options` | array | — | ISO periods to hide from the date picker, such as `["P3M", "P6M"]`. Ignored when it would hide every option |
| `enable_percent_change_toggle` | boolean | `false` | Adds a toggle between absolute values and percent change |
| `absolute_toggle_label` | string | `"$"` | Label for the absolute-value toggle button, such as `"€"` or `"MW"` |
| `percent_toggle_label` | string | `"%"` | Label for the percent-change toggle button, such as `"YoY %"` |
| `end_of_line_labels` | boolean | `false` | Shows a label at the end of each line on multi-series charts |
| `show_kicker_boxes` | boolean | `false` | Renders a stock box above the chart for each dataset that has a `kicker` |
| `enable_client_side_filtering` | boolean | `true` | Filters date ranges in the browser without a server call |
| `disable_view_toggle` | boolean | — | Hides the view selector |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
Each dataset has:
| Field | Type | Required | Description |
| - | - | - | - |
| `label` | string | Yes | Series name in the legend |
| `data` | array | Yes | Points with `x` (a date string, timestamp, or number) and `y` (a number or `null`) |
| `type` | `"line"` \| `"bar"` \| `"scatter"` | No | Chart type for this series |
| `units` | string | No | Value units, such as `"$"`, `"%"`, or `"USD"` |
| `kicker` | string | No | Exchange label for the stock box, such as `"NASDAQ"` |
| `title` | string | No | Company or series name shown above the ticker in the stock box |
| `color`, `color_light_mode`, `color_dark_mode` | string | No | See [Color Overrides](#color-overrides) |
## Example: Bar Chart
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Revenue by Region",
"source": "Internal Analytics",
"components": [
{
"component_type": "header",
"config": {
"title": "Revenue by Region"
}
},
{
"component_type": "categorical_bar",
"config": {
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "North", "y": 120000},
{"x": "South", "y": 98000},
{"x": "East", "y": 87000},
{"x": "West", "y": 145000}
],
"units": "$"
}
]
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Revenue by Region",
source="Internal Analytics",
components=[
ComponentConfig(
component_type="header",
config={"title": "Revenue by Region"},
),
ComponentConfig(
component_type="categorical_bar",
config={
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "North", "y": 120000},
{"x": "South", "y": 98000},
{"x": "East", "y": 87000},
{"x": "West", "y": 145000}
],
"units": "$"
}
]
},
),
],
))
```
### Header Fields
| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | Header title. When the request has no `title`, the first header's title becomes the card title |
| `subtitle` | string | No | Line below the title |
### Bar Chart Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | Categorical datasets (see below). One dataset draws a single series; several draw a grouped chart |
| `title` | string | — | Tooltip title |
| `default_view` | `"vertical"` \| `"horizontal"` \| `"grouped"` \| `"stacked"` | `"vertical"` for one dataset, `"grouped"` for several | Initial view. One dataset supports `vertical` and `horizontal`; several support `grouped` and `stacked` |
| `sort_series_by` | `"value"` \| `"alphabetical"` | `"value"` | Series order in grouped charts. `value` sorts by each series' value at the first category |
| `sort_series_direction` | `"asc"` \| `"desc"` | `"desc"` | Sort direction |
| `disable_view_toggle` | boolean | — | Hides the view selector, so the chart stays in its default view |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
Categorical datasets are also used by `data_table_chart`, `pie`, `treemap`, `histogram`, and `choropleth`. Each one has:
| Field | Type | Required | Description |
| - | - | - | - |
| `label` | string | Yes | Series name in the legend |
| `data` | array | Yes | Points with `x` (a category label) and `y` (a number). Every point needs a numeric `y`, or the request fails with a 400 that names the points |
| `data[].highlight` | boolean | No | Emphasizes this bar. With `series_color_theme: "uniform"`, the highlighted bar gets the accent color and the rest are muted |
| `data[].color` | string | No | Hex color for this point. Honored by `categorical_bar`, `data_table_chart`, and `choropleth` |
| `units` | string | No | Value units, such as `"$"` or `"%"` |
| `color`, `color_light_mode`, `color_dark_mode` | string | No | See [Color Overrides](#color-overrides) |
## Example: Data Table Chart
A bar chart with an auto-generated data table below showing the values:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Q4 Sales by Product",
"source": "Sales Team",
"components": [
{
"component_type": "header",
"config": {
"title": "Q4 Sales by Product"
}
},
{
"component_type": "data_table_chart",
"config": {
"datasets": [
{
"label": "Units Sold",
"data": [
{"x": "Widget A", "y": 1200},
{"x": "Widget B", "y": 850},
{"x": "Widget C", "y": 2100}
]
}
]
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Q4 Sales by Product",
source="Sales Team",
components=[
ComponentConfig(
component_type="header",
config={"title": "Q4 Sales by Product"},
),
ComponentConfig(
component_type="data_table_chart",
config={
"datasets": [
{
"label": "Units Sold",
"data": [
{"x": "Widget A", "y": 1200},
{"x": "Widget B", "y": 850},
{"x": "Widget C", "y": 2100}
]
}
]
},
),
],
))
```
### Data Table Chart Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | [categorical datasets](#bar-chart-fields). One dataset draws a single series; several draw a grouped chart |
| `title` | string | — | Tooltip title |
| `default_view` | `"vertical"` \| `"horizontal"` \| `"grouped"` \| `"stacked"` | `"vertical"` for one dataset, `"grouped"` for several | Initial view, as in `categorical_bar` |
| `series_color_theme` | string | `"uniform"` for one dataset | See [Shared Config Options](#shared-config-options). |
| `legend` | object | — | See [Shared Config Options](#shared-config-options). |
## Example: Financial Boxes
Display financial metrics with growth indicators:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "AAPL Financials",
"source": "SEC Filings",
"components": [
{
"component_type": "financial_boxes",
"config": {
"items": [
{
"header": "Revenue",
"value": "$94.9B",
"growth": {"formattedValue": "6.1% YoY", "value": 0.061}
},
{
"header": "Net Income",
"value": "$23.6B",
"growth": {"formattedValue": "-3.4% YoY", "value": -0.034}
},
{
"header": "EPS",
"value": "$1.64"
}
]
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="AAPL Financials",
source="SEC Filings",
components=[
ComponentConfig(
component_type="financial_boxes",
config={
"items": [
{
"header": "Revenue",
"value": "$94.9B",
"growth": {"formattedValue": "6.1% YoY", "value": 0.061}
},
{
"header": "Net Income",
"value": "$23.6B",
"growth": {"formattedValue": "-3.4% YoY", "value": -0.034}
},
{"header": "EPS", "value": "$1.64"}
]
},
),
],
))
```
Growth indicator colors are automatic: positive `value` appears green, negative appears red.
### Financial Boxes Fields
`items` is required. Each item has:
| Field | Type | Required | Description |
| - | - | - | - |
| `header` | string | Yes | Metric name, such as `"Revenue"` |
| `value` | string | No | Preformatted value, such as `"$10.5B"` |
| `growth` | object | No | Growth indicator with `formattedValue` (the displayed text, such as `"5.25% YoY"`) and `value` (a number whose sign sets the color, such as `0.0525` for 5.25%) |
## Example: Top-Level Metric
Show one large headline number or phrase with a caption:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "US Unemployment Rate",
"source": "Bureau of Labor Statistics",
"components": [
{
"component_type": "top_level_metric",
"config": {
"accent_text": "As of March 2024",
"headline": "3.8%",
"subheadline": "US unemployment rate",
"description": "Seasonally adjusted share of the labor force that is unemployed."
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="US Unemployment Rate",
source="Bureau of Labor Statistics",
components=[
ComponentConfig(
component_type="top_level_metric",
config={
"accent_text": "As of March 2024",
"headline": "3.8%",
"subheadline": "US unemployment rate",
"description": "Seasonally adjusted share of the labor force that is unemployed."
},
),
],
))
```
### Top-Level Metric Fields
| Field | Type | Required | Description |
| - | - | - | - |
| `headline` | string | Yes | Large headline text |
| `subheadline` | string | Yes | Caption below the headline |
| `accent_text` | string | No | Small line above the headline |
| `description` | string | No | Longer text below the metric |
## Example: Data Table
A configurable table with columns, sorting, and pagination:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Product Performance",
"components": [
{
"component_type": "table",
"config": {
"columns": [
{"field": "name", "label": "Product", "type": "string"},
{"field": "revenue", "label": "Revenue", "type": "currency", "units": "$"},
{"field": "growth", "label": "Growth", "type": "percent", "units": "%"},
{"field": "rating", "label": "Rating", "type": "rating"},
{"field": "in_stock", "label": "In Stock", "type": "boolean"}
],
"rows": [
{"name": "Product A", "revenue": 1500000, "growth": 15.0, "rating": 4, "in_stock": true},
{"name": "Product B", "revenue": 2300000, "growth": -5.0, "rating": 3, "in_stock": true},
{"name": "Product C", "revenue": 980000, "growth": 22.3, "rating": 5, "in_stock": false}
],
"searchable": true,
"paginated": true,
"rows_per_page": 25,
"initial_sort_field": "revenue",
"initial_sort_order": "desc",
"highlight_best": true
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Product Performance",
components=[
ComponentConfig(
component_type="table",
config={
"columns": [
{"field": "name", "label": "Product", "type": "string"},
{
"field": "revenue",
"label": "Revenue",
"type": "currency",
"units": "$"
},
{
"field": "growth",
"label": "Growth",
"type": "percent",
"units": "%"
},
{"field": "rating", "label": "Rating", "type": "rating"},
{
"field": "in_stock",
"label": "In Stock",
"type": "boolean"
}
],
"rows": [
{
"name": "Product A",
"revenue": 1500000,
"growth": 15.0,
"rating": 4,
"in_stock": True
},
{
"name": "Product B",
"revenue": 2300000,
"growth": -5.0,
"rating": 3,
"in_stock": True
},
{
"name": "Product C",
"revenue": 980000,
"growth": 22.3,
"rating": 5,
"in_stock": False
}
],
"searchable": True,
"paginated": True,
"rows_per_page": 25,
"initial_sort_field": "revenue",
"initial_sort_order": "desc",
"highlight_best": True
},
),
],
))
```
### Table Column Types
| Type | Rendering | Default Alignment |
| - | - | - |
| `string` | Plain text | Left |
| `number` | Formatted with units | Right |
| `date` | Date values | Left |
| `percent` | Percentage formatting | Right |
| `currency` | Right-aligned with currency formatting (uses `units` field) | Right |
| `boolean` | Checkmarks (✓/✗) with green/red colors | Center |
| `rating` | Stars (★★★☆☆) clamped to 1-5 range | Center |
### Table Config Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `columns` | array | *required* | Column definitions (see column types above) |
| `rows` | array | *required* | Row data as list of objects. Keys should match column `field` values |
| `title` | string | — | Optional title displayed above the table |
| `searchable` | boolean | `false` | Enable search/filter functionality |
| `paginated` | boolean | `false` | Enable pagination |
| `rows_per_page` | integer | `25` | Number of rows per page when paginated |
| `initial_sort_field` | string | — | Field to sort by initially |
| `initial_sort_order` | `"asc"` \| `"desc"` | `"desc"` | Initial sort direction |
| `highlight_best` | boolean | `false` | Highlight the best value in numeric columns with a green background. For currency: lowest is best. For number/rating: highest is best. Only highlights when there is a unique winner |
Each column also supports an optional `align` field (`"left"`, `"right"`, or `"center"`) to override the default alignment.
When `highlight_best` is enabled, the best value in each currency, number, and rating column is highlighted with a green background. Currency columns treat the lowest value as best; number and rating columns treat the highest value as best. Boolean columns are excluded — they use checkmark colors instead.
## Example: Timeline
A timeline showing events or periods along a time axis:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Product Launch Timeline",
"source": "Product Team",
"components": [
{
"component_type": "timeline",
"config": {
"events": [
{
"start_date": "2024-01-15",
"end_date": "2024-03-30",
"label": "Research & Design",
"value": "2.5 months"
},
{
"start_date": "2024-04-01",
"end_date": "2024-07-15",
"label": "Development",
"value": "3.5 months"
},
{
"start_date": "2024-07-16",
"end_date": "2024-08-31",
"label": "Beta Testing",
"value": "1.5 months"
},
{
"start_date": "2024-09-01",
"end_date": "2024-09-15",
"label": "Launch",
"value": "2 weeks",
"color": "#22C55E"
}
],
"title": "Product Launch Timeline"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Product Launch Timeline",
source="Product Team",
components=[
ComponentConfig(
component_type="timeline",
config={
"events": [
{
"start_date": "2024-01-15",
"end_date": "2024-03-30",
"label": "Research & Design",
"value": "2.5 months"
},
{
"start_date": "2024-04-01",
"end_date": "2024-07-15",
"label": "Development",
"value": "3.5 months"
},
{
"start_date": "2024-07-16",
"end_date": "2024-08-31",
"label": "Beta Testing",
"value": "1.5 months"
},
{
"start_date": "2024-09-01",
"end_date": "2024-09-15",
"label": "Launch",
"value": "2 weeks",
"color": "#22C55E"
}
],
"title": "Product Launch Timeline"
},
),
],
))
```
### Timeline Fields
| Field | Type | Required | Description |
| - | - | - | - |
| `events` | array | Yes | List of timeline events (see below) |
| `title` | string | No | Chart title |
| `series_color_theme` | string | No | Color theme for events |
| `timeline_mode` | `"absolute"` \| `"ordinal"` | No | X-axis spacing mode. `absolute` spaces events proportional to real dates. `ordinal` spaces events evenly. Auto-detected if not set |
| `ordinal_label_prefix` | string | No | Prefix for ordinal x-axis labels (e.g., `"Week"` renders as "Week 1", "Week 2") |
Each event in the `events` array has:
| Field | Type | Required | Description |
| - | - | - | - |
| `start_date` | string | Yes | Start date in ISO format (e.g., `"2024-01-15"`) |
| `end_date` | string | Yes | End date in ISO format (e.g., `"2024-06-30"`) |
| `label` | string | Yes | Event label |
| `value` | string | No | Value to display (e.g., duration, cost) |
| `color` | string | No | Override color for this event (hex format, e.g., `"#FF5733"`) |
When `timeline_mode` is not set, the mode is auto-detected based on the distribution of events. Use `"ordinal"` mode when events have very different time gaps and you want them spaced evenly, or `"absolute"` mode when the proportional time spacing is meaningful.
## Example: Pie Chart
Show proportional data as slices of a circle:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Browser Market Share",
"source": "Statcounter",
"components": [
{
"component_type": "pie",
"config": {
"datasets": [
{
"label": "Share",
"data": [
{"x": "Chrome", "y": 65.2},
{"x": "Safari", "y": 18.7},
{"x": "Edge", "y": 5.4},
{"x": "Firefox", "y": 3.0},
{"x": "Other", "y": 7.7}
],
"units": "%"
}
],
"title": "Global Desktop Browser Share"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Browser Market Share",
source="Statcounter",
components=[
ComponentConfig(
component_type="pie",
config={
"datasets": [
{
"label": "Share",
"data": [
{"x": "Chrome", "y": 65.2},
{"x": "Safari", "y": 18.7},
{"x": "Edge", "y": 5.4},
{"x": "Firefox", "y": 3.0},
{"x": "Other", "y": 7.7}
],
"units": "%"
}
],
"title": "Global Desktop Browser Share"
},
),
],
))
```
Each data point uses `x` for the slice label and `y` for the value. Slices are colored automatically from the theme palette.
### Pie Chart Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | [categorical datasets](#bar-chart-fields). Each point's `x` is a slice label and `y` its value. Only the first dataset is drawn |
| `title` | string | — | Tooltip title |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Histogram
Bin raw values into a frequency distribution:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Order Value Distribution",
"source": "Internal Analytics",
"components": [
{
"component_type": "histogram",
"config": {
"datasets": [
{
"label": "Order Values",
"data": [
{"x": "1", "y": 12.50}, {"x": "2", "y": 18.30}, {"x": "3", "y": 22.10},
{"x": "4", "y": 25.00}, {"x": "5", "y": 28.40}, {"x": "6", "y": 31.20},
{"x": "7", "y": 33.50}, {"x": "8", "y": 35.00}, {"x": "9", "y": 38.20},
{"x": "10", "y": 41.00}, {"x": "11", "y": 42.50}, {"x": "12", "y": 45.00},
{"x": "13", "y": 47.30}, {"x": "14", "y": 50.00}, {"x": "15", "y": 52.10},
{"x": "16", "y": 55.00}, {"x": "17", "y": 58.40}, {"x": "18", "y": 62.00},
{"x": "19", "y": 68.50}, {"x": "20", "y": 75.20}, {"x": "21", "y": 82.00},
{"x": "22", "y": 90.10}, {"x": "23", "y": 95.00}, {"x": "24", "y": 105.00},
{"x": "25", "y": 120.00}
],
"units": "$"
}
],
"title": "Order Values ($)",
"num_bins": 8
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Order Value Distribution",
source="Internal Analytics",
components=[
ComponentConfig(
component_type="histogram",
config={
"datasets": [
{
"label": "Order Values",
"data": [
{"x": "1", "y": 12.50},
{"x": "2", "y": 18.30},
{"x": "3", "y": 22.10},
{"x": "4", "y": 25.00},
{"x": "5", "y": 28.40},
{"x": "6", "y": 31.20},
{"x": "7", "y": 33.50},
{"x": "8", "y": 35.00},
{"x": "9", "y": 38.20},
{"x": "10", "y": 41.00},
{"x": "11", "y": 42.50},
{"x": "12", "y": 45.00},
{"x": "13", "y": 47.30},
{"x": "14", "y": 50.00},
{"x": "15", "y": 52.10},
{"x": "16", "y": 55.00},
{"x": "17", "y": 58.40},
{"x": "18", "y": 62.00},
{"x": "19", "y": 68.50},
{"x": "20", "y": 75.20},
{"x": "21", "y": 82.00},
{"x": "22", "y": 90.10},
{"x": "23", "y": 95.00},
{"x": "24", "y": 105.00},
{"x": "25", "y": 120.00}
],
"units": "$"
}
],
"title": "Order Values ($)",
"num_bins": 8
},
),
],
))
```
The `y` values are the raw data — bins are computed automatically. Use `num_bins` to set the number of bins, or `bin_width` to set a fixed width.
### Histogram Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | [categorical datasets](#bar-chart-fields). Each point's `y` is one raw value to bin. Only the first dataset is drawn |
| `num_bins` | integer | `10` | Number of bins |
| `bin_width` | number | — | Width of each bin. Overrides `num_bins` |
| `title` | string | — | Tooltip title |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Scatter Plot
Show the relationship between two continuous variables:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Height vs Weight",
"source": "Survey Data",
"components": [
{
"component_type": "scatter",
"config": {
"datasets": [
{
"label": "Participants",
"data": [
{"x": 165, "y": 60, "label": "P1"},
{"x": 170, "y": 68, "label": "P2"},
{"x": 175, "y": 72, "label": "P3"},
{"x": 180, "y": 78, "label": "P4"},
{"x": 185, "y": 85, "label": "P5"},
{"x": 190, "y": 92, "label": "P6"}
],
"x_units": "cm",
"y_units": "kg"
}
],
"title": "Height vs Weight",
"x_axis_label": "Height (cm)",
"y_axis_label": "Weight (kg)"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Height vs Weight",
source="Survey Data",
components=[
ComponentConfig(
component_type="scatter",
config={
"datasets": [
{
"label": "Participants",
"data": [
{"x": 165, "y": 60, "label": "P1"},
{"x": 170, "y": 68, "label": "P2"},
{"x": 175, "y": 72, "label": "P3"},
{"x": 180, "y": 78, "label": "P4"},
{"x": 185, "y": 85, "label": "P5"},
{"x": 190, "y": 92, "label": "P6"}
],
"x_units": "cm",
"y_units": "kg"
}
],
"title": "Height vs Weight",
"x_axis_label": "Height (cm)",
"y_axis_label": "Weight (kg)"
},
),
],
))
```
Each data point's optional `label` is shown in the tooltip on hover.
### Scatter Plot Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | Datasets (see below) |
| `title` | string | — | Tooltip title |
| `x_axis_label`, `y_axis_label` | string | — | Axis labels |
| `show_point_labels` | boolean | `false` | Shows each point's `label` next to the point. When `false`, labels appear only in the tooltip |
| `show_horizontal_grid` | boolean | `false` | Draws horizontal grid lines at the y-axis ticks |
| `y_axis_position` | `"left"` \| `"right"` | `"right"` | Side of the y-axis. With `left`, point labels move to the right of each point |
| `y_axis_min` | number | Automatic | Lower bound of the y-axis, with a tick at that value |
| `y_axis_step` | number | Automatic | Spacing between y-axis ticks |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
Each dataset has:
| Field | Type | Required | Description |
| - | - | - | - |
| `label` | string | Yes | Series name in the legend |
| `data` | array | Yes | Points with numeric `x` and `y`, and an optional `label` |
| `x_units`, `y_units` | string | No | Units for each axis |
| `highlight` | boolean | No | Draws this dataset's point labels in the dataset color. It doesn't change the point color |
| `color`, `color_light_mode`, `color_dark_mode` | string | No | See [Color Overrides](#color-overrides) |
## Example: Bubble Chart
A scatter plot with a size dimension — useful for plotting three variables at once:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Product Performance",
"source": "Internal Analytics",
"components": [
{
"component_type": "bubble",
"config": {
"datasets": [
{
"label": "Products",
"data": [
{"x": 4.2, "y": 12.5, "r": 15, "label": "Widget A"},
{"x": 3.8, "y": 18.2, "r": 22, "label": "Widget B"},
{"x": 4.6, "y": 8.7, "r": 30, "label": "Widget C"},
{"x": 3.5, "y": 22.0, "r": 12, "label": "Widget D"},
{"x": 4.8, "y": 15.3, "r": 25, "label": "Widget E"}
]
}
],
"title": "Rating vs Margin (bubble = revenue)",
"x_axis_label": "Avg Rating (out of 5)",
"y_axis_label": "Margin (%)"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Product Performance",
source="Internal Analytics",
components=[
ComponentConfig(
component_type="bubble",
config={
"datasets": [
{
"label": "Products",
"data": [
{"x": 4.2, "y": 12.5, "r": 15, "label": "Widget A"},
{"x": 3.8, "y": 18.2, "r": 22, "label": "Widget B"},
{"x": 4.6, "y": 8.7, "r": 30, "label": "Widget C"},
{"x": 3.5, "y": 22.0, "r": 12, "label": "Widget D"},
{"x": 4.8, "y": 15.3, "r": 25, "label": "Widget E"}
]
}
],
"title": "Rating vs Margin (bubble = revenue)",
"x_axis_label": "Avg Rating (out of 5)",
"y_axis_label": "Margin (%)"
},
),
],
))
```
The third dimension is encoded as bubble radius via `r` on each data point.
### Bubble Chart Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | Same shape as [scatter datasets](#scatter-plot-fields). Each point also needs `r`, the value that sets its size |
| `title` | string | — | Chart title |
| `x_axis_label`, `y_axis_label` | string | — | Axis labels |
| `show_point_labels` | boolean | `false` | Shows each point's `label` next to the point |
| `show_horizontal_grid` | boolean | `false` | Draws horizontal grid lines at the y-axis ticks |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Choropleth Map
Color geographic regions by value. `map_type` is `"us_states"` or `"world"`:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Population by State",
"source": "US Census",
"components": [
{
"component_type": "choropleth",
"config": {
"datasets": [
{
"label": "Population (millions)",
"data": [
{"x": "California", "y": 39.0},
{"x": "Texas", "y": 30.5},
{"x": "Florida", "y": 22.6},
{"x": "New York", "y": 19.5},
{"x": "Pennsylvania", "y": 12.9},
{"x": "Illinois", "y": 12.5},
{"x": "Ohio", "y": 11.8},
{"x": "Georgia", "y": 11.0},
{"x": "North Carolina", "y": 10.7},
{"x": "Michigan", "y": 10.0}
],
"units": "M"
}
],
"title": "US State Population",
"map_type": "us_states"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Population by State",
source="US Census",
components=[
ComponentConfig(
component_type="choropleth",
config={
"datasets": [
{
"label": "Population (millions)",
"data": [
{"x": "California", "y": 39.0},
{"x": "Texas", "y": 30.5},
{"x": "Florida", "y": 22.6},
{"x": "New York", "y": 19.5},
{"x": "Pennsylvania", "y": 12.9},
{"x": "Illinois", "y": 12.5},
{"x": "Ohio", "y": 11.8},
{"x": "Georgia", "y": 11.0},
{"x": "North Carolina", "y": 10.7},
{"x": "Michigan", "y": 10.0}
],
"units": "M"
}
],
"title": "US State Population",
"map_type": "us_states"
},
),
],
))
```
For US states, `x` is the full state name (e.g. `"California"`). For world maps, use `"map_type": "world"` and country names.
### Choropleth Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | [categorical datasets](#bar-chart-fields). Each point's `x` is a region name (a US state or a country) and `y` its value. Only the first dataset is drawn |
| `map_type` | `"us_states"` \| `"world"` | `"us_states"` | Which map to draw |
| `title` | string | — | Chart title |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Heatmap
A 2D grid where color encodes value. Useful for things like correlation matrices or activity by day-and-hour:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Sales by Day & Shift",
"source": "POS System",
"components": [
{
"component_type": "heatmap",
"config": {
"data": [
{"x": "Mon", "y": "Morning", "v": 12},
{"x": "Mon", "y": "Midday", "v": 38},
{"x": "Mon", "y": "Afternoon", "v": 22},
{"x": "Mon", "y": "Evening", "v": 45},
{"x": "Tue", "y": "Morning", "v": 15},
{"x": "Tue", "y": "Midday", "v": 42},
{"x": "Tue", "y": "Afternoon", "v": 28},
{"x": "Tue", "y": "Evening", "v": 50},
{"x": "Wed", "y": "Morning", "v": 18},
{"x": "Wed", "y": "Midday", "v": 45},
{"x": "Wed", "y": "Afternoon", "v": 30},
{"x": "Wed", "y": "Evening", "v": 55},
{"x": "Thu", "y": "Morning", "v": 20},
{"x": "Thu", "y": "Midday", "v": 48},
{"x": "Thu", "y": "Afternoon", "v": 35},
{"x": "Thu", "y": "Evening", "v": 62},
{"x": "Fri", "y": "Morning", "v": 25},
{"x": "Fri", "y": "Midday", "v": 55},
{"x": "Fri", "y": "Afternoon", "v": 40},
{"x": "Fri", "y": "Evening", "v": 78}
],
"title": "Orders by Day & Shift",
"x_axis_label": "Day",
"y_axis_label": "Shift",
"v_label": "Orders"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Sales by Day & Shift",
source="POS System",
components=[
ComponentConfig(
component_type="heatmap",
config={
"data": [
{"x": "Mon", "y": "Morning", "v": 12},
{"x": "Mon", "y": "Midday", "v": 38},
{"x": "Mon", "y": "Afternoon", "v": 22},
{"x": "Mon", "y": "Evening", "v": 45},
{"x": "Tue", "y": "Morning", "v": 15},
{"x": "Tue", "y": "Midday", "v": 42},
{"x": "Tue", "y": "Afternoon", "v": 28},
{"x": "Tue", "y": "Evening", "v": 50},
{"x": "Wed", "y": "Morning", "v": 18},
{"x": "Wed", "y": "Midday", "v": 45},
{"x": "Wed", "y": "Afternoon", "v": 30},
{"x": "Wed", "y": "Evening", "v": 55},
{"x": "Thu", "y": "Morning", "v": 20},
{"x": "Thu", "y": "Midday", "v": 48},
{"x": "Thu", "y": "Afternoon", "v": 35},
{"x": "Thu", "y": "Evening", "v": 62},
{"x": "Fri", "y": "Morning", "v": 25},
{"x": "Fri", "y": "Midday", "v": 55},
{"x": "Fri", "y": "Afternoon", "v": 40},
{"x": "Fri", "y": "Evening", "v": 78}
],
"title": "Orders by Day & Shift",
"x_axis_label": "Day",
"y_axis_label": "Shift",
"v_label": "Orders"
},
),
],
))
```
Heatmap takes a flat `data` array of `{x, y, v}` points (not a `datasets` list). `v` is the value used to determine color intensity.
### Heatmap Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `data` | array | *required* | Cells with `x` and `y` category labels and a numeric `v` (or `null`) that sets the color intensity |
| `title` | string | — | Chart title |
| `x_axis_label`, `y_axis_label` | string | — | Axis labels |
| `v_label` | string | — | Name of the value, shown in tooltips |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Box Plot
Show the statistical distribution (min, Q1, median, Q3, max) of values across categories. Provide raw values per category — quartiles are computed for you:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Response Time by Region",
"source": "Telemetry",
"components": [
{
"component_type": "boxplot",
"config": {
"categories": [
{
"category": "US-East",
"values": [42, 48, 51, 55, 58, 60, 62, 65, 68, 72, 75, 80, 85, 90, 110]
},
{
"category": "US-West",
"values": [38, 42, 45, 48, 50, 52, 55, 58, 62, 65, 70, 75, 82, 95, 120]
},
{
"category": "EU",
"values": [55, 60, 65, 70, 75, 80, 85, 90, 95, 100, 110, 120, 135, 150, 180]
},
{
"category": "APAC",
"values": [80, 90, 100, 110, 120, 130, 140, 150, 160, 175, 190, 210, 240, 280, 350]
}
],
"title": "p50/p95 Response Time by Region",
"y_axis_label": "Response time",
"units": "ms"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Response Time by Region",
source="Telemetry",
components=[
ComponentConfig(
component_type="boxplot",
config={
"categories": [
{
"category": "US-East",
"values": [
42,
48,
51,
55,
58,
60,
62,
65,
68,
72,
75,
80,
85,
90,
110
]
},
{
"category": "US-West",
"values": [
38,
42,
45,
48,
50,
52,
55,
58,
62,
65,
70,
75,
82,
95,
120
]
},
{
"category": "EU",
"values": [
55,
60,
65,
70,
75,
80,
85,
90,
95,
100,
110,
120,
135,
150,
180
]
},
{
"category": "APAC",
"values": [
80,
90,
100,
110,
120,
130,
140,
150,
160,
175,
190,
210,
240,
280,
350
]
}
],
"title": "p50/p95 Response Time by Region",
"y_axis_label": "Response time",
"units": "ms"
},
),
],
))
```
Box plot uses `categories` (not `datasets`) and each category has a `values` array of raw numbers.
### Box Plot Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `categories` | array | *required* | Entries with a `category` label and a `values` array of raw numbers. Tako computes the minimum, quartiles, median, and maximum |
| `title` | string | — | Chart title |
| `y_axis_label` | string | — | Y-axis label |
| `units` | string | — | Value units |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Treemap
Show hierarchical data as area-proportional rectangles — good for spend breakdowns or composition:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Cloud Spend by Service",
"source": "AWS Cost Explorer",
"components": [
{
"component_type": "treemap",
"config": {
"datasets": [
{
"label": "Monthly Spend",
"data": [
{"x": "EC2", "y": 12500},
{"x": "RDS", "y": 6800},
{"x": "S3", "y": 3200},
{"x": "Lambda", "y": 1450},
{"x": "CloudFront", "y": 980},
{"x": "DynamoDB", "y": 720},
{"x": "ElastiCache", "y": 540},
{"x": "Other", "y": 410}
],
"units": "$"
}
],
"title": "AWS Spend by Service ($)"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Cloud Spend by Service",
source="AWS Cost Explorer",
components=[
ComponentConfig(
component_type="treemap",
config={
"datasets": [
{
"label": "Monthly Spend",
"data": [
{"x": "EC2", "y": 12500},
{"x": "RDS", "y": 6800},
{"x": "S3", "y": 3200},
{"x": "Lambda", "y": 1450},
{"x": "CloudFront", "y": 980},
{"x": "DynamoDB", "y": 720},
{"x": "ElastiCache", "y": 540},
{"x": "Other", "y": 410}
],
"units": "$"
}
],
"title": "AWS Spend by Service ($)"
},
),
],
))
```
Each rectangle's area is proportional to its `y` value.
### Treemap Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `datasets` | array | *required* | [categorical datasets](#bar-chart-fields). Each point's `x` is a rectangle label and `y` sets its area. Only the first dataset is drawn |
| `title` | string | — | Tooltip title |
| `legend`, `series_color_theme` | | | See [Shared Config Options](#shared-config-options). |
## Example: Waterfall
Show how a starting value changes through a series of additions and subtractions to reach an ending value. Use `is_anchor: true` for totals/subtotals (bars that start at zero):
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Income Statement",
"source": "Q3 Earnings",
"components": [
{
"component_type": "waterfall",
"config": {
"items": [
{"category": "Revenue", "value": 100.0, "is_anchor": true},
{"category": "COGS", "value": -38.0},
{"category": "Gross Profit", "value": 62.0, "is_anchor": true},
{"category": "OpEx", "value": -28.0},
{"category": "Operating Income", "value": 34.0, "is_anchor": true},
{"category": "Tax", "value": -7.0},
{"category": "Net Income", "value": 27.0, "is_anchor": true}
],
"title": "Q3 Income Breakdown",
"units": "$"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Income Statement",
source="Q3 Earnings",
components=[
ComponentConfig(
component_type="waterfall",
config={
"items": [
{"category": "Revenue", "value": 100.0, "is_anchor": True},
{"category": "COGS", "value": -38.0},
{
"category": "Gross Profit",
"value": 62.0,
"is_anchor": True
},
{"category": "OpEx", "value": -28.0},
{
"category": "Operating Income",
"value": 34.0,
"is_anchor": True
},
{"category": "Tax", "value": -7.0},
{"category": "Net Income", "value": 27.0, "is_anchor": True}
],
"title": "Q3 Income Breakdown",
"units": "$"
},
),
],
))
```
By default, positive deltas are green and negative deltas are red. Anchor bars (`is_anchor: true`) are drawn as solid bars rising from zero.
### Waterfall Fields
| Field | Type | Default | Description |
| - | - | - | - |
| `items` | array | *required* | Entries with a `category` label, a `value` (the change, positive or negative), and an optional `is_anchor`. An anchor bar starts from zero, so use it for totals such as net income |
| `title` | string | — | Chart title |
| `units` | string | — | Value units |
| `series_color_theme` | string | `"red_bad_green_good"` | See [Shared Config Options](#shared-config-options). |
| `legend` | object | — | See [Shared Config Options](#shared-config-options). |
## Example: Sankey
Show directed flows between nodes — revenue splitting into cost and profit branches, a user funnel, energy flow, or any weighted graph. Provide a list of `nodes` and a list of `links`; every link's `source` and `target` must reference a node `id`. Links must form a DAG (no cycles or self-loops); duplicate `(source, target)` pairs are summed.
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Q1 Income Statement",
"source": "Company Financials",
"components": [
{
"component_type": "sankey",
"config": {
"nodes": [
{"id": "data_center", "label": "Data Center"},
{"id": "gaming", "label": "Gaming"},
{"id": "revenue", "label": "Revenue"},
{"id": "cogs", "label": "Cost of Revenue", "polarity": "negative"},
{"id": "gross", "label": "Gross Profit", "polarity": "positive"},
{"id": "opex", "label": "Operating Expenses", "polarity": "negative"},
{"id": "op_profit", "label": "Operating Profit", "polarity": "positive"},
{"id": "tax", "label": "Tax", "polarity": "negative"},
{"id": "net_profit", "label": "Net Profit", "polarity": "positive"}
],
"links": [
{"source": "data_center", "target": "revenue", "value": 22.6},
{"source": "gaming", "target": "revenue", "value": 2.6},
{"source": "revenue", "target": "cogs", "value": 5.6},
{"source": "revenue", "target": "gross", "value": 20.4},
{"source": "gross", "target": "opex", "value": 3.5},
{"source": "gross", "target": "op_profit", "value": 17.3},
{"source": "op_profit", "target": "tax", "value": 2.4},
{"source": "op_profit", "target": "net_profit","value": 14.9}
],
"title": "Revenue to Net Profit",
"units": "$B"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Q1 Income Statement",
source="Company Financials",
components=[
ComponentConfig(
component_type="sankey",
config={
"nodes": [
{"id": "data_center", "label": "Data Center"},
{"id": "gaming", "label": "Gaming"},
{"id": "revenue", "label": "Revenue"},
{
"id": "cogs",
"label": "Cost of Revenue",
"polarity": "negative"
},
{
"id": "gross",
"label": "Gross Profit",
"polarity": "positive"
},
{
"id": "opex",
"label": "Operating Expenses",
"polarity": "negative"
},
{
"id": "op_profit",
"label": "Operating Profit",
"polarity": "positive"
},
{"id": "tax", "label": "Tax", "polarity": "negative"},
{
"id": "net_profit",
"label": "Net Profit",
"polarity": "positive"
}
],
"links": [
{
"source": "data_center",
"target": "revenue",
"value": 22.6
},
{"source": "gaming", "target": "revenue", "value": 2.6},
{"source": "revenue", "target": "cogs", "value": 5.6},
{"source": "revenue", "target": "gross", "value": 20.4},
{"source": "gross", "target": "opex", "value": 3.5},
{"source": "gross", "target": "op_profit", "value": 17.3},
{"source": "op_profit", "target": "tax", "value": 2.4},
{
"source": "op_profit",
"target": "net_profit",
"value": 14.9
}
],
"title": "Revenue to Net Profit",
"units": "$B"
},
),
],
))
```
A node's `polarity` sets its color: `positive` renders green, `negative` red, and `neutral` (the default) gray. Each flow shades from its source node's color to its target node's color. Use this to make a profit-vs-cost story read at a glance — leave upstream/source nodes neutral so only the meaningful splits carry color.
### Sankey fields
| Field | Required | Description |
| - | - | - |
| `nodes` | yes | List of nodes (min 2). Each has `id` (canonical key) and `label` (display string), plus optional `polarity`. |
| `nodes[].polarity` | no | `positive`, `negative`, or `neutral` (default). Sets the node's color, which the flows into and out of it shade toward. |
| `links` | yes | List of directed flows (min 1). Each has `source` (node id), `target` (node id), and `value` (positive number). |
| `title` | no | Chart title. |
| `units` | no | Units for flow values (e.g. `$`, `$B`, `%`), used in tooltips. |
## Example: Marimekko
Show a two-level part-to-whole breakdown as a mosaic of variable-width stacked columns — market share by region and brand, spend by department and category, or contract obligations by agency and vendor. Each column's width is proportional to its total, and each stacked segment's height is its share within that column. Marimekko takes the same flat `data` array of `{x, y, v}` points as the heatmap: `x` is the column (X dimension), `y` is the stacked segment (Y dimension), and `v` is the cell magnitude.
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Smartphone Market Share",
"source": "Internal Analytics",
"components": [
{
"component_type": "marimekko",
"config": {
"data": [
{"x": "North America", "y": "Apple", "v": 52},
{"x": "North America", "y": "Samsung", "v": 28},
{"x": "North America", "y": "Google", "v": 9},
{"x": "Europe", "y": "Samsung", "v": 34},
{"x": "Europe", "y": "Apple", "v": 31},
{"x": "Europe", "y": "Xiaomi", "v": 18},
{"x": "Asia Pacific", "y": "Xiaomi", "v": 25},
{"x": "Asia Pacific", "y": "Samsung", "v": 22},
{"x": "Asia Pacific", "y": "Oppo", "v": 19},
{"x": "Asia Pacific", "y": "Apple", "v": 15}
],
"title": "Units Sold by Region & Brand",
"x_axis_label": "Region",
"y_axis_label": "Brand",
"units": "M units",
"top_n_columns": 8,
"top_m_segments": 6
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Smartphone Market Share",
source="Internal Analytics",
components=[
ComponentConfig(
component_type="marimekko",
config={
"data": [
{"x": "North America", "y": "Apple", "v": 52},
{"x": "North America", "y": "Samsung", "v": 28},
{"x": "North America", "y": "Google", "v": 9},
{"x": "Europe", "y": "Samsung", "v": 34},
{"x": "Europe", "y": "Apple", "v": 31},
{"x": "Europe", "y": "Xiaomi", "v": 18},
{"x": "Asia Pacific", "y": "Xiaomi", "v": 25},
{"x": "Asia Pacific", "y": "Samsung", "v": 22},
{"x": "Asia Pacific", "y": "Oppo", "v": 19},
{"x": "Asia Pacific", "y": "Apple", "v": 15}
],
"title": "Units Sold by Region & Brand",
"x_axis_label": "Region",
"y_axis_label": "Brand",
"units": "M units",
"top_n_columns": 8,
"top_m_segments": 6
},
),
],
))
```
Cells that share an `(x, y)` pair are summed first; a pair is then dropped only if its net value is non-positive (so a downward adjustment nets against a positive value in the same cell rather than being dropped on its own). The largest `top_n_columns` columns and, within each, the largest `top_m_segments` segments render individually; everything else rolls into an "Other" column / "Other" segment so the mosaic always conserves the total. Segments are colored from the theme palette and labeled on the chart canvas (no separate legend).
### Marimekko fields
| Field | Required | Description |
| - | - | - |
| `data` | yes | List of `{x, y, v}` cells. `x` is the column label, `y` is the stacked segment label, `v` is the cell magnitude. |
| `title` | no | Chart title. |
| `x_axis_label` | no | Label for the columns dimension (e.g. `Region`). |
| `y_axis_label` | no | Label for the segments dimension (e.g. `Brand`). |
| `units` | no | Units for values (e.g. `$`, `%`), used in tooltips and on-canvas labels. |
| `top_n_columns` | no | Columns shown individually before the rest roll into an "Other" column (default `8`). |
| `top_m_segments` | no | Segments shown individually per column before the rest roll into an "Other" segment (default `6`). |
## Example: Person Card
Build a profile card with career, education, and about tabs from an [Exa](https://exa.ai) person search result. Pass the Exa result object as the `config`. A `person_card` must be the only component in the request.
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"components": [
{
"component_type": "person_card",
"config": {
"title": "Jane Doe | Engineer - Acme Corp",
"url": "https://linkedin.com/in/janedoe",
"image": "https://example.com/photo.jpg",
"highlights": ["Technical Skills: Python, Go, TypeScript"],
"entities": [
{
"id": "https://exa.ai/library/person/jane-doe",
"type": "person",
"properties": {
"name": "Jane Doe",
"location": "San Francisco, CA",
"workHistory": [
{
"title": "Senior Engineer",
"company": {"name": "Acme Corp"},
"dates": {"from": "2021-03", "to": null}
}
],
"educationHistory": [
{
"degree": "BS Computer Science",
"institution": {"name": "State University"},
"dates": {"from": "2013", "to": "2017"}
}
]
}
}
]
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
components=[
ComponentConfig(
component_type="person_card",
config={
"title": "Jane Doe | Engineer - Acme Corp",
"url": "https://linkedin.com/in/janedoe",
"image": "https://example.com/photo.jpg",
"highlights": ["Technical Skills: Python, Go, TypeScript"],
"entities": [
{
"id": "https://exa.ai/library/person/jane-doe",
"type": "person",
"properties": {
"name": "Jane Doe",
"location": "San Francisco, CA",
"workHistory": [
{
"title": "Senior Engineer",
"company": {"name": "Acme Corp"},
"dates": {"from": "2021-03", "to": None}
}
],
"educationHistory": [
{
"degree": "BS Computer Science",
"institution": {"name": "State University"},
"dates": {"from": "2013", "to": "2017"}
}
]
}
}
]
},
),
],
))
```
### Person Card Fields
| Field | Type | Required | Description |
| - | - | - | - |
| `entities` | array | Yes | Exa person entities, each with an `id`, `type: "person"`, and `properties`. Tako reads the first one |
| `title` | string | No | Exa result title, such as `"Jane Doe \| Engineer - Acme Corp"` |
| `url` | string | No | Profile URL |
| `author` | string | No | Person's name |
| `image` | string | No | Profile image URL |
| `highlights` | array | No | Text highlights. Tako extracts skills from them |
An entity's `properties` accept `name`, `firstName`, `lastName`, `location`, `workHistory` (entries with `title`, `location`, `company.name`, and `dates.from` and `dates.to`), and `educationHistory` (entries with `degree`, `institution.name`, and `dates`).
The card title is the person's name, taken from `properties.name`, then `author`, then the part of `title` before the `|`. A request-level `title` overrides it.
## Combining Multiple Components
Cards can contain multiple components stacked together. This lets you build richer visualizations by pairing related data.
### Financial Boxes + Timeseries Chart
Pair summary metrics with a trend chart:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "AAPL Quarterly Overview",
"source": "SEC Filings",
"components": [
{
"component_type": "financial_boxes",
"config": {
"items": [
{
"header": "Revenue",
"value": "$94.9B",
"growth": {"formattedValue": "6.1% YoY", "value": 0.061}
},
{
"header": "Net Income",
"value": "$23.6B",
"growth": {"formattedValue": "-3.4% YoY", "value": -0.034}
},
{
"header": "EPS",
"value": "$1.64"
}
]
}
},
{
"component_type": "generic_timeseries",
"config": {
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "2023-Q1", "y": 94.8},
{"x": "2023-Q2", "y": 81.8},
{"x": "2023-Q3", "y": 89.5},
{"x": "2023-Q4", "y": 119.6},
{"x": "2024-Q1", "y": 90.8},
{"x": "2024-Q2", "y": 85.8},
{"x": "2024-Q3", "y": 94.9}
],
"units": "$"
}
],
"chart_type": "bar",
"title": "Quarterly Revenue ($B)"
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="AAPL Quarterly Overview",
source="SEC Filings",
components=[
ComponentConfig(
component_type="financial_boxes",
config={
"items": [
{
"header": "Revenue",
"value": "$94.9B",
"growth": {"formattedValue": "6.1% YoY", "value": 0.061}
},
{
"header": "Net Income",
"value": "$23.6B",
"growth": {"formattedValue": "-3.4% YoY", "value": -0.034}
},
{"header": "EPS", "value": "$1.64"}
]
},
),
ComponentConfig(
component_type="generic_timeseries",
config={
"datasets": [
{
"label": "Revenue",
"data": [
{"x": "2023-Q1", "y": 94.8},
{"x": "2023-Q2", "y": 81.8},
{"x": "2023-Q3", "y": 89.5},
{"x": "2023-Q4", "y": 119.6},
{"x": "2024-Q1", "y": 90.8},
{"x": "2024-Q2", "y": 85.8},
{"x": "2024-Q3", "y": 94.9}
],
"units": "$"
}
],
"chart_type": "bar",
"title": "Quarterly Revenue ($B)"
},
),
],
))
```
### Header + Bar Chart
Add a styled header above any chart:
```bash cURL theme={null}
curl -X POST https://tako.com/api/v1/thin_viz/create/ \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Team Headcount",
"components": [
{
"component_type": "header",
"config": {
"title": "Team Headcount by Department",
"subtitle": "As of January 2025"
}
},
{
"component_type": "categorical_bar",
"config": {
"datasets": [
{
"label": "Headcount",
"data": [
{"x": "Engineering", "y": 142},
{"x": "Sales", "y": 89},
{"x": "Marketing", "y": 54},
{"x": "Operations", "y": 67}
]
}
]
}
}
]
}'
```
```python Python theme={null}
# Reuses the client from the first example above
card = client.create_card(CreateCardRequest(
title="Team Headcount",
components=[
ComponentConfig(
component_type="header",
config={
"title": "Team Headcount by Department",
"subtitle": "As of January 2025"
},
),
ComponentConfig(
component_type="categorical_bar",
config={
"datasets": [
{
"label": "Headcount",
"data": [
{"x": "Engineering", "y": 142},
{"x": "Sales", "y": 89},
{"x": "Marketing", "y": 54},
{"x": "Operations", "y": 67}
]
}
]
},
),
],
))
```
Components render in the order they appear in the `components` array - top to bottom on the card.
## Available Components
| Component | Description |
| - | - |
| [`header`](#header-fields) | Card header with title and optional subtitle |
| [`generic_timeseries`](#creating-a-card) | Line, bar, or scatter timeseries charts |
| [`categorical_bar`](#example-bar-chart) | Bar chart with categorical x-axis (regions, products, etc.) |
| [`data_table_chart`](#example-data-table-chart) | Bar chart with auto-generated data table below |
| [`financial_boxes`](#example-financial-boxes) | Financial metric boxes with values and growth indicators |
| [`table`](#example-data-table) | Data table with configurable columns (string, number, date, percent, currency, boolean, rating), sorting, formatting, and pagination |
| [`timeline`](#example-timeline) | Timeline chart showing events or periods along a time axis |
| [`pie`](#example-pie-chart) | Pie chart showing proportional data as slices of a circle |
| [`histogram`](#example-histogram) | Histogram chart showing frequency distribution of values |
| [`scatter`](#example-scatter-plot) | Scatter plot showing relationships between two continuous variables |
| [`bubble`](#example-bubble-chart) | Bubble chart (scatter plot with size dimension) for 3-variable data |
| [`choropleth`](#example-choropleth-map) | Choropleth map showing geographic data with color intensity by region |
| [`heatmap`](#example-heatmap) | 2D heatmap with color intensity representing values |
| [`boxplot`](#example-box-plot) | Box plot showing statistical distributions (min, Q1, median, Q3, max) |
| [`treemap`](#example-treemap) | Treemap chart showing hierarchical data as proportional rectangles |
| [`waterfall`](#example-waterfall) | Waterfall chart showing incremental positive/negative changes |
| [`sankey`](#example-sankey) | Sankey diagram showing directed flows between nodes (revenue → cost/profit, funnels, energy flow) |
| [`marimekko`](#example-marimekko) | Marimekko (mosaic) chart showing a two-level part-to-whole breakdown as variable-width stacked columns (region × brand, agency × vendor) |
| [`top_level_metric`](#example-top-level-metric) | One large headline number or phrase with a caption |
| [`person_card`](#example-person-card) | Person profile with career, education, and about tabs, built from an Exa person search result |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.