Thin-Viz - Tako Docs

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.

cURL
Python

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"
        }
      }
    ]
  }'

pip install tako-sdk

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:

{
  "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)
`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

Embedding Your Card

Use the embed_url from the response in an iframe:

<iframe
  src="https://tako.com/embed/abc123xyz"
  width="600"
  height="400"
  frameborder="0"
></iframe>

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:

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": [ ... ]
  }'

# 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:

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
        }
      }
    ]
  }'

# 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.

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

Example: Bar Chart

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": "$"
            }
          ]
        }
      }
    ]
  }'

# 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.

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

Example: Data Table Chart

A bar chart with an auto-generated data table below showing the values:

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}
              ]
            }
          ]
        }
      }
    ]
  }'

# 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. 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.
`legend`	object	—	See Shared Config Options.

Example: Financial Boxes

Display financial metrics with growth indicators:

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"
            }
          ]
        }
      }
    ]
  }'

# 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:

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."
        }
      }
    ]
  }'

# 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:

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
        }
      }
    ]
  }'

# 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:

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"
        }
      }
    ]
  }'

# 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:

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"
        }
      }
    ]
  }'

# 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. 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.

Example: Histogram

Bin raw values into a frequency distribution:

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
        }
      }
    ]
  }'

# 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. 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.

Example: Scatter Plot

Show the relationship between two continuous variables:

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)"
        }
      }
    ]
  }'

# 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.

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

Example: Bubble Chart

A scatter plot with a size dimension — useful for plotting three variables at once:

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 (%)"
        }
      }
    ]
  }'

# 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. 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.

Example: Choropleth Map

Color geographic regions by value. map_type is "us_states" or "world":

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"
        }
      }
    ]
  }'

# 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. 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.

Example: Heatmap

A 2D grid where color encodes value. Useful for things like correlation matrices or activity by day-and-hour:

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"
        }
      }
    ]
  }'

# 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.

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:

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"
        }
      }
    ]
  }'

# 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.

Example: Treemap

Show hierarchical data as area-proportional rectangles — good for spend breakdowns or composition:

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 ($)"
        }
      }
    ]
  }'

# 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. 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.

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):

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": "$"
        }
      }
    ]
  }'

# 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.
`legend`	object	—	See 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.

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"
        }
      }
    ]
  }'

# 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.

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
        }
      }
    ]
  }'

# 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 person search result. Pass the Exa result object as the config. A person_card must be the only component in the request.

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"}
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }'

# 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:

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)"
        }
      }
    ]
  }'

# 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)"
            },
        ),
    ],
))

Add a styled header above any chart:

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}
              ]
            }
          ]
        }
      }
    ]
  }'

# 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`	Card header with title and optional subtitle
`generic_timeseries`	Line, bar, or scatter timeseries charts
`categorical_bar`	Bar chart with categorical x-axis (regions, products, etc.)
`data_table_chart`	Bar chart with auto-generated data table below
`financial_boxes`	Financial metric boxes with values and growth indicators
`table`	Data table with configurable columns (string, number, date, percent, currency, boolean, rating), sorting, formatting, and pagination
`timeline`	Timeline chart showing events or periods along a time axis
`pie`	Pie chart showing proportional data as slices of a circle
`histogram`	Histogram chart showing frequency distribution of values
`scatter`	Scatter plot showing relationships between two continuous variables
`bubble`	Bubble chart (scatter plot with size dimension) for 3-variable data
`choropleth`	Choropleth map showing geographic data with color intensity by region
`heatmap`	2D heatmap with color intensity representing values
`boxplot`	Box plot showing statistical distributions (min, Q1, median, Q3, max)
`treemap`	Treemap chart showing hierarchical data as proportional rectangles
`waterfall`	Waterfall chart showing incremental positive/negative changes
`sankey`	Sankey diagram showing directed flows between nodes (revenue → cost/profit, funnels, energy flow)
`marimekko`	Marimekko (mosaic) chart showing a two-level part-to-whole breakdown as variable-width stacked columns (region × brand, agency × vendor)
`top_level_metric`	One large headline number or phrase with a caption
`person_card`	Person profile with career, education, and about tabs, built from an Exa person search result

​Why Thin-Viz

​Creating a Card

​Request Fields

​Embedding Your Card

​Preview Images for ZDR Cards

​Shared Config Options

​Color Overrides

​Example: Stock Card with Kicker Boxes

​Timeseries Fields

​Example: Bar Chart

​Header Fields

​Bar Chart Fields

​Example: Data Table Chart

​Data Table Chart Fields

​Example: Financial Boxes

​Financial Boxes Fields

​Example: Top-Level Metric

​Top-Level Metric Fields

​Example: Data Table

​Table Column Types

​Table Config Fields

​Example: Timeline

​Timeline Fields

​Example: Pie Chart

​Pie Chart Fields

​Example: Histogram

​Histogram Fields

​Example: Scatter Plot

​Scatter Plot Fields

​Example: Bubble Chart

​Bubble Chart Fields

​Example: Choropleth Map

​Choropleth Fields

​Example: Heatmap

​Heatmap Fields

​Example: Box Plot

​Box Plot Fields

​Example: Treemap

​Treemap Fields

​Example: Waterfall

​Waterfall Fields

​Example: Sankey

​Sankey fields

​Example: Marimekko

​Marimekko fields

​Example: Person Card

​Person Card Fields

​Combining Multiple Components

​Financial Boxes + Timeseries Chart

​Header + Bar Chart

​Available Components

Why Thin-Viz

Creating a Card

Request Fields

Embedding Your Card

Preview Images for ZDR Cards

Shared Config Options

Color Overrides

Example: Stock Card with Kicker Boxes

Timeseries Fields

Example: Bar Chart

Header Fields

Bar Chart Fields

Example: Data Table Chart

Data Table Chart Fields

Example: Financial Boxes

Financial Boxes Fields

Example: Top-Level Metric

Top-Level Metric Fields

Example: Data Table

Table Column Types

Table Config Fields

Example: Timeline

Timeline Fields

Example: Pie Chart

Pie Chart Fields

Example: Histogram

Histogram Fields

Example: Scatter Plot

Scatter Plot Fields

Example: Bubble Chart

Bubble Chart Fields

Example: Choropleth Map

Choropleth Fields

Example: Heatmap

Heatmap Fields

Example: Box Plot

Box Plot Fields

Example: Treemap

Treemap Fields

Example: Waterfall

Waterfall Fields

Example: Sankey

Sankey fields

Example: Marimekko

Marimekko fields

Example: Person Card

Person Card Fields

Combining Multiple Components

Financial Boxes + Timeseries Chart

Header + Bar Chart

Available Components