Charts

Create chart

post/v0/boards/{boardId}/charts

Request

  • Base URL: https://api.formo.so
  • URL: https://api.formo.so/v0/boards/{boardId}/charts
  • Auth: HTTP bearer

Path parameters

boardIdstring required

Headers

Idempotency-Keystring

Optional unique value (e.g. a UUID v4) that lets you safely retry POST/PUT/PATCH/DELETE requests. The first request runs normally; subsequent requests with the same key replay the stored response (status + body) for 24 hours, so retries can never double-create or double-charge. Two concurrent requests with the same key return 409 IDEMPOTENCY_IN_PROGRESS. Generate a fresh key per logical operation.

Request body

projectIdstring required

Project the chart belongs to.

querystring

SQL query that powers the chart.

  • funnel: pass "SELECT 1"; the actual query is auto-generated from steps.
  • user_paths: omit it; the query is generated from settings.anchors.
  • retention: omit it; data is fetched automatically.
  • All other types: required; must be a valid SQL string.
chart_type'table' | 'number' | 'funnel' | 'bar' | 'line' | 'area' | 'pie' | 'stacked' | 'user_paths' | 'retention' required

Visualization type. Determines which other fields are required:

chart_typeExtra required fields
tablequery
numberquery (must return 1 row × 1 column)
barquery, x_axis, y_axis (≥ 1)
linequery, x_axis, y_axis (≥ 1)
areaquery, x_axis, y_axis (≥ 1; exactly 1 if group_by set)
piequery, y_axis (exactly 1)
stackedquery, x_axis, y_axis (exactly 1), group_by
funnelsteps (≥ 2), query placeholder "SELECT 1"
user_pathssettings.anchors (≥ 1); query is generated
retentionsettings.entryFilter (key required; null means any event)
titlestring required

Display name shown on the chart and board.

descriptionstring

Optional description.

x_axisstring

Column name for the X axis. Required for bar, line, and stacked.

y_axisstring[]

Column name(s) used as Y axis metrics.

  • bar / line: at least 1 element required.
  • pie / stacked: exactly 1 element required.
group_bystring

Column to group / stack series by. Required for stacked.

Response

Chart created

idstring required
chart_type'table' | 'number' | 'funnel' | 'bar' | 'line' | 'area' | 'pie' | 'stacked' | 'user_paths' | 'retention' required

Visualization type.

titlestring required
descriptionstring nullable
querystring required

SQL query powering the chart. For funnel and retention charts this is a system-managed placeholder.

project_idstring required
board_idstring required
x_axisstring nullable

Column used as the X axis.

y_axisstring[] nullable

Column(s) used as Y axis metric(s).

group_bystring nullable

Column used to group/stack series.

Changes

No recorded changes to this operation across all 1 revision of this API.