Skip to main content
POST
/
v1
/
excel
/
jobs
Generate Chart
curl --request POST \
  --url https://api.stru.ai/v1/excel/jobs \
  --header 'Content-Type: application/json' \
  --data '{
  "chart_type": "<string>",
  "title": "<string>",
  "data_range": "<string>",
  "x_axis": "<string>",
  "y_axis": "<string>",
  "options": {}
}'

​
Overview

Generate charts and graphs in Excel spreadsheets from data tables. Add professional visualizations to your dynamically generated reports without manual chart creation.
Charts are created as part of the create_spreadsheet operation using chart blocks. This endpoint reference shows how to use chart blocks effectively.

​
Chart Block Structure

Include chart blocks in your spreadsheet creation request: 
{
  "type": "chart",
  "chart_type": "bar",
  "title": "Cost Breakdown",
  "data_range": "MATERIALS",  // Reference to named table
  "x_axis": "Material",
  "y_axis": "Total Cost",
  "options": {
    "legend_position": "right",
    "colors": ["#16A34A", "#07C983", "#15803D"]
  }
}

​
Chart Types

​
chart_type
string
required
Type of chart to generateOptions:
  • "bar" - Vertical bar chart
  • "column" - Horizontal bar chart
  • "line" - Line chart
  • "pie" - Pie chart
  • "scatter" - Scatter plot
  • "area" - Area chart

​
Chart Options

​
title
string
Chart title
"title": "Project Cost Distribution"
​
data_range
string
required
Name of the data table to visualize (must be defined earlier in the sheet)
"data_range": "MATERIALS"
​
x_axis
string
Column name for X-axis
"x_axis": "Material"
​
y_axis
string
Column name for Y-axis
"y_axis": "Total Cost"
​
options
object
Additional chart configuration
"options": {
  "legend_position": "right",
  "show_data_labels": true,
  "colors": ["#16A34A", "#07C983"]
}

​
Example Request

curl -X POST https://api.stru.ai/v1/excel/jobs \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "create_spreadsheet",
    "workbook_name": "Project Summary with Charts",
    "sheets": [
      {
        "name": "Materials",
        "blocks": [
          {
            "type": "header",
            "content": "Material Cost Analysis"
          },
          {
            "type": "data_table",
            "name": "MATERIALS",
            "headers": ["Material", "Quantity", "Unit Price", "Total Cost"],
            "rows": [
              ["Concrete", 150, 175, 26250],
              ["Rebar", 8000, 1.25, 10000],
              ["Formwork", 2500, 8.5, 21250]
            ]
          },
          {
            "type": "chart",
            "chart_type": "bar",
            "title": "Cost Breakdown by Material",
            "data_range": "MATERIALS",
            "x_axis": "Material",
            "y_axis": "Total Cost",
            "options": {
              "legend_position": "bottom",
              "show_data_labels": true
            }
          }
        ]
      }
    ]
  }'

​
Chart Examples by Type

​
Bar Chart

{
  "type": "chart",
  "chart_type": "bar",
  "title": "Quantity by Material",
  "data_range": "MATERIALS",
  "x_axis": "Material",
  "y_axis": "Quantity"
}

​
Line Chart

{
  "type": "chart",
  "chart_type": "line",
  "title": "Cost Trend Over Time",
  "data_range": "MONTHLY_COSTS",
  "x_axis": "Month",
  "y_axis": "Total Cost",
  "options": {
    "smooth_lines": true
  }
}

​
Pie Chart

{
  "type": "chart",
  "chart_type": "pie",
  "title": "Cost Distribution",
  "data_range": "COSTS",
  "x_axis": "Category",
  "y_axis": "Amount",
  "options": {
    "show_percentages": true
  }
}

​
Scatter Plot

{
  "type": "chart",
  "chart_type": "scatter",
  "title": "Load vs Deflection",
  "data_range": "TEST_DATA",
  "x_axis": "Load",
  "y_axis": "Deflection",
  "options": {
    "show_trendline": true
  }
}

​
Use Cases

Create visual dashboards with multiple charts showing project metrics.
charts = [
    {"chart_type": "pie", "title": "Cost by Category"},
    {"chart_type": "line", "title": "Budget Burn Rate"},
    {"chart_type": "bar", "title": "Hours by Phase"}
]
Visualize project progress with timeline charts and completion percentages.
{
    "chart_type": "column",
    "title": "Weekly Progress",
    "data_range": "WEEKLY_DATA",
    "x_axis": "Week",
    "y_axis": ["Planned", "Actual"]
}
Create technical charts for load-deflection curves, moment diagrams, etc.
{
    "chart_type": "scatter",
    "title": "Load-Deflection Curve",
    "data_range": "TEST_RESULTS",
    "x_axis": "Deflection_in",
    "y_axis": "Load_kip",
    "options": {"show_trendline": true}
}

​
Best Practices

Define data first - Always create the data table block before the chart block
Use named tables - Reference tables by name for clarity and maintainability
Choose appropriate chart type - Match chart type to data (bar for categories, line for trends, pie for proportions)
Add titles - Always include descriptive chart titles
For multi-series charts (comparing Budget vs Actual), pass an array for y_axis: "y_axis": ["Budget", "Actual"]

​
Chart Customization Options

OptionTypeDescriptionDefault
legend_positionstringPosition of legend: "top", "bottom", "left", "right""right"
show_data_labelsbooleanShow values on data pointsfalse
colorsarrayCustom color palette (hex codes)Default Excel colors
smooth_linesbooleanSmooth line chartsfalse
show_trendlinebooleanAdd trendline (scatter/line charts)false
show_percentagesbooleanShow percentages (pie charts)false

​
Next Steps

After generating a spreadsheet with charts:
  1. Download the .xlsx file
  2. Open in Excel to view the visualizations
  3. Charts are fully editable in Excel if adjustments are needed