Create Chart - Formo Docs

curl --request POST \
  --url https://api.formo.so/v0/boards/{boardId}/charts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel",
  "steps": [
    {
      "type": "event",
      "event": "page"
    },
    {
      "type": "event",
      "event": "connect"
    },
    {
      "type": "event",
      "event": "transaction"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 7,
      "unit": "day"
    }
  }
}
'

{
  "id": "<string>",
  "title": "<string>",
  "query": "<string>",
  "project_id": "<string>",
  "board_id": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "event": "<string>"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 2
    },
    "startStep": {
      "event": "<string>"
    },
    "endStep": {
      "event": "<string>"
    },
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "event": "<string>"
    },
    "retentionUserFilters": [
      {
        "field": "<string>",
        "value": "<string>"
      }
    ],
    "retentionSignalType": "event",
    "retentionLabelSignal": {
      "tag_id": "<string>",
      "op": "greater",
      "value": "<string>",
      "chain_id": ""
    }
  }
}

POST

boards

{boardId}

charts

curl --request POST \
  --url https://api.formo.so/v0/boards/{boardId}/charts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel",
  "steps": [
    {
      "type": "event",
      "event": "page"
    },
    {
      "type": "event",
      "event": "connect"
    },
    {
      "type": "event",
      "event": "transaction"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 7,
      "unit": "day"
    }
  }
}
'

{
  "id": "<string>",
  "title": "<string>",
  "query": "<string>",
  "project_id": "<string>",
  "board_id": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "event": "<string>"
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 2
    },
    "startStep": {
      "event": "<string>"
    },
    "endStep": {
      "event": "<string>"
    },
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "event": "<string>"
    },
    "retentionUserFilters": [
      {
        "field": "<string>",
        "value": "<string>"
      }
    ],
    "retentionSignalType": "event",
    "retentionLabelSignal": {
      "tag_id": "<string>",
      "op": "greater",
      "value": "<string>",
      "chain_id": ""
    }
  }
}

Overview

Creates a new chart and attaches it to a board. Returns the full chart object on success. The chart_type field controls which other request body fields are required or validated. Funnel charts are special - their SQL is auto-generated from the steps array, so pass "SELECT 1" as the query placeholder.

Request Fields

Field	Type	Required	Description
`projectId`	string	Yes	Project the chart belongs to
`query`	string	Conditional	SQL query. Required for all types except `retention`. For `funnel`, pass `"SELECT 1"`
`chart_type`	string	Yes	`table` · `number` · `bar` · `line` · `area` · `pie` · `stacked` · `funnel` · `user_paths` · `retention`
`title`	string	Yes	Display name (minimum 1 character)
`description`	string	No	Optional description
`x_axis`	string	Conditional	Column for the X axis. Required for `bar`, `line`, `area`, `stacked`
`y_axis`	string[]	Conditional	Column(s) for Y axis metrics. See per-type rules below
`group_by`	string	Conditional	Column to group/stack series by. Required for `stacked`
`steps`	FunnelStep[]	Conditional	Ordered funnel steps. Required for `funnel` (minimum 2)
`settings`	ChartSettings	No	Type-specific configuration object

Chart Types

`table`

Renders query results in a paginated table. No axis fields needed.

{
  "projectId": "proj_abc",
  "query": "SELECT * FROM events ORDER BY timestamp DESC LIMIT 10",
  "chart_type": "table",
  "title": "Recent Events"
}

`number`

Renders a single scalar value (KPI card). The query must return exactly 1 row × 1 column.

{
  "projectId": "proj_abc",
  "query": "SELECT COUNT(DISTINCT address) FROM events WHERE type = 'connect'",
  "chart_type": "number",
  "title": "Total Connected Wallets"
}

`bar`, `line`, and `area`

All three require x_axis and at least 1 column in y_axis. area requires exactly 1 column in y_axis when group_by is set.

{
  "projectId": "proj_abc",
  "query": "SELECT toDate(timestamp) AS date, countDistinct(address) AS users FROM events GROUP BY date ORDER BY date DESC LIMIT 30",
  "chart_type": "line",
  "title": "Daily Active Users",
  "x_axis": "date",
  "y_axis": ["users"]
}

`pie`

Requires exactly 1 column in y_axis. x_axis identifies the label column.

{
  "projectId": "proj_abc",
  "query": "SELECT device, COUNT(*) AS session_count FROM sessions GROUP BY device ORDER BY session_count DESC LIMIT 10",
  "chart_type": "pie",
  "title": "Sessions by Device",
  "x_axis": "device",
  "y_axis": ["session_count"]
}

`stacked`

Requires x_axis, exactly 1 column in y_axis, and group_by.

{
  "projectId": "proj_abc",
  "query": "SELECT device, browser, COUNT(*) AS session_count FROM sessions GROUP BY device, browser ORDER BY session_count DESC",
  "chart_type": "stacked",
  "title": "Sessions by Device and Browser",
  "x_axis": "device",
  "y_axis": ["session_count"],
  "group_by": "browser"
}

Funnel Charts

Funnel charts measure step-by-step user conversion. The SQL is auto-generated from steps, so query must be the placeholder "SELECT 1". At least 2 steps are required.

The `FunnelStep` Object

Each step in the steps array has the following shape:

{
  "type": "event | track | decoded_log",
  "event": "<event name>",
  "<propertyKey>": { "op": "<operator>", "value": "<value>" }
}

Field	Type	Required	Description
`type`	string	Yes	`event` - built-in events (page, connect, transaction); `track` - custom tracked events; `decoded_log` - decoded smart-contract events
`event`	string	Yes	Event name (e.g. `page`, `connect`, `transaction`)
`<propertyKey>`	`StepFilterCondition`	No	One or more property filters. Any extra key on the step object is treated as a filter. Standard columns (`device`, `browser`, `os`, `location`, `referrer`, `ref`, `utm_*`) are filtered directly; all other keys are extracted from `properties` via `JSONExtractString`

Filter Operators (`StepFilterCondition`)

{ "op": "<operator>", "value": "<value>" }

`op`	SQL equivalent	Notes
`equals`	`= 'value'`	Exact match
`notEquals`	`!= 'value'`	Inverse match
`in`	`IN (...)`	Pipe-delimited value: `"metamask\|rainbow\|coinbase"`
`notIn`	`NOT IN (...)`	Pipe-delimited value
`gt`	`> value`	Numeric comparison
`gte`	`>= value`	Numeric comparison
`lt`	`< value`	Numeric comparison
`lte`	`<= value`	Numeric comparison
`startsWith`	`startsWith(col, 'v')`	String prefix
`endsWith`	`endsWith(col, 'v')`	String suffix
`includes`	`like '%v%'`	Substring match

For in and notIn, join multiple values with a pipe |. Escape a literal pipe with \| and a literal backslash with \\.

`settings` for Funnel Charts

Field	Type	Default	Description
`funnelType`	`"closed"` \| `"open"`	`"closed"`	`closed` - strict ordering, no events between steps; `open` - ordered but other events may occur between steps
`conversionWindow`	`ConversionWindow`	2 days	Max time from Step 1 for a user to complete all steps
`breakdown`	string	-	Split each funnel bar by this dimension

`ConversionWindow`

{ "value": 7, "unit": "day" }

unit must be one of: hour · day · week (7 days).

`breakdown` values

device · browser · os · location · referrer · ref · utm_source · utm_medium · utm_campaign · utm_term · utm_content · builder_codes The top categories are shown individually. The rest collapse into “Others”.

Funnel Examples

Basic 3-step closed funnel

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel",
  "steps": [
    { "type": "event", "event": "page" },
    { "type": "event", "event": "connect" },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 7, "unit": "day" }
  }
}

With per-step property filters

Filter step 2 to MetaMask wallets on Ethereum mainnet:

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "MetaMask Conversion Funnel",
  "steps": [
    { "type": "event", "event": "page" },
    {
      "type": "event",
      "event": "connect",
      "rdns": { "op": "equals", "value": "io.metamask" },
      "chain_id": { "op": "equals", "value": "1" }
    },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 7, "unit": "day" }
  }
}

With breakdown by device

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel by Device",
  "steps": [
    { "type": "event", "event": "page" },
    { "type": "event", "event": "connect" },
    { "type": "event", "event": "signature" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 30, "unit": "day" },
    "breakdown": "device"
  }
}

Open funnel with multi-value `in` filter

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Mobile Onboarding Funnel",
  "steps": [
    {
      "type": "event",
      "event": "page",
      "device": { "op": "equals", "value": "mobile" }
    },
    {
      "type": "event",
      "event": "connect",
      "provider_name": { "op": "in", "value": "metamask|rainbow|coinbase" }
    },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "open",
    "conversionWindow": { "value": 30, "unit": "day" },
    "breakdown": "device"
  }
}

User Paths Charts

Visualize how users navigate your app after a starting event. settings.startStep is required.

`settings` for User Paths Charts

Field	Type	Default	Description
`startStep`	`FunnelStep`	-	Required. Event where the flow begins
`endStep`	`FunnelStep` \| `null`	`null`	Optional ending event. `null` = open-ended
`maxSteps`	integer (2 to 5)	`3`	Max steps to show in the flow. Values above 5 are clamped to 5
`nodesPerStep`	integer (2 to 8)	`5`	Max unique event nodes per step. Values above 8 are clamped to 8
`conversionWindow`	`ConversionWindow`	-	Time window to group the flow
`filters`	string	-	JSON-encoded string of additional path filters

{
  "projectId": "proj_abc",
  "query": "SELECT anonymous_id, type AS event, timestamp FROM events WHERE timestamp >= today() - INTERVAL 30 DAY ORDER BY anonymous_id, timestamp",
  "chart_type": "user_paths",
  "title": "Post-Connect User Flow",
  "settings": {
    "startStep": { "type": "event", "event": "connect" },
    "endStep": { "type": "event", "event": "transaction" },
    "maxSteps": 5,
    "conversionWindow": { "value": 2, "unit": "week" }
  }
}

Retention Charts

Measures how often users return over time. The query field is not used - pass "" or omit it.

`settings` for Retention Charts

Field	Type	Description
`retentionFilter`	`FunnelStep` \| `null`	Event that qualifies a returning visit as “retained”. `null` = any event counts
`retentionUserFilters`	`RetentionUserFilter[]`	User-segment filters that narrow the retention cohort

Each RetentionUserFilter:

Field	Type	Description
`field`	string	User property (e.g. `device`, `browser`, `os`, `utm_source`, `location`)
`op`	string	Comparison operator (same set as `StepFilterCondition.op`)
`value`	string \| number	Value to compare against

{
  "projectId": "proj_abc",
  "query": "",
  "chart_type": "retention",
  "title": "Weekly Retention - Desktop Users",
  "settings": {
    "retentionFilter": { "type": "event", "event": "transaction" },
    "retentionUserFilters": [
      { "field": "device", "op": "equals", "value": "desktop" },
      { "field": "utm_source", "op": "notEquals", "value": "direct" }
    ]
  }
}

For all-user retention with no filters, omit settings:

{
  "projectId": "proj_abc",
  "query": "",
  "chart_type": "retention",
  "title": "Overall Retention"
}

Validation Reference

Chart Type	Validation Rule
`table`	`query` must execute successfully
`number`	`query` must return exactly 1 row × 1 column
`bar`	`x_axis` required; `y_axis` requires ≥ 1 element
`line`	`x_axis` required; `y_axis` requires ≥ 1 element
`pie`	`y_axis` requires exactly 1 element
`stacked`	`x_axis` required; `y_axis` requires exactly 1 element; `group_by` required
`funnel`	`steps` requires ≥ 2 `FunnelStep` objects; `query` must be `"SELECT 1"` or any valid SQL
`user_paths`	`settings.startStep` required; `query` must execute and return valid path data
`retention`	No query validation - `query` is ignored

Response

201 Created - returns the full chart object.

{
  "id": "chart_1a2b3c4d",
  "chart_type": "table",
  "title": "Recent Events",
  "description": null,
  "query": "SELECT * FROM events ORDER BY timestamp DESC LIMIT 10",
  "project_id": "proj_abc",
  "board_id": "board_xyz"
}

Use the returned id with the Get Chart, Update Chart, and Delete Chart endpoints. 400 Bad Request - validation failed (missing required fields, invalid SQL, wrong step count, etc.). Branch on error.code; see Errors.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Funnel chart must have at least 2 steps",
    "doc_url": "https://docs.formo.so/api/errors#bad_request"
  }
}

Overview

Request Fields

Field	Type	Required	Description
`projectId`	string	Yes	Project the chart belongs to
`query`	string	Conditional	SQL query. Required for all types except `retention`. For `funnel`, pass `"SELECT 1"`
`chart_type`	string	Yes	`table` · `number` · `bar` · `line` · `area` · `pie` · `stacked` · `funnel` · `user_paths` · `retention`
`title`	string	Yes	Display name (minimum 1 character)
`description`	string	No	Optional description
`x_axis`	string	Conditional	Column for the X axis. Required for `bar`, `line`, `area`, `stacked`
`y_axis`	string[]	Conditional	Column(s) for Y axis metrics. See per-type rules below
`group_by`	string	Conditional	Column to group/stack series by. Required for `stacked`
`steps`	FunnelStep[]	Conditional	Ordered funnel steps. Required for `funnel` (minimum 2)
`settings`	ChartSettings	No	Type-specific configuration object

Chart Types

`table`

Renders query results in a paginated table. No axis fields needed.

{
  "projectId": "proj_abc",
  "query": "SELECT * FROM events ORDER BY timestamp DESC LIMIT 10",
  "chart_type": "table",
  "title": "Recent Events"
}

`number`

Renders a single scalar value (KPI card). The query must return exactly 1 row × 1 column.

{
  "projectId": "proj_abc",
  "query": "SELECT COUNT(DISTINCT address) FROM events WHERE type = 'connect'",
  "chart_type": "number",
  "title": "Total Connected Wallets"
}

`bar`, `line`, and `area`

All three require x_axis and at least 1 column in y_axis. area requires exactly 1 column in y_axis when group_by is set.

{
  "projectId": "proj_abc",
  "query": "SELECT toDate(timestamp) AS date, countDistinct(address) AS users FROM events GROUP BY date ORDER BY date DESC LIMIT 30",
  "chart_type": "line",
  "title": "Daily Active Users",
  "x_axis": "date",
  "y_axis": ["users"]
}

`pie`

Requires exactly 1 column in y_axis. x_axis identifies the label column.

{
  "projectId": "proj_abc",
  "query": "SELECT device, COUNT(*) AS session_count FROM sessions GROUP BY device ORDER BY session_count DESC LIMIT 10",
  "chart_type": "pie",
  "title": "Sessions by Device",
  "x_axis": "device",
  "y_axis": ["session_count"]
}

`stacked`

Requires x_axis, exactly 1 column in y_axis, and group_by.

{
  "projectId": "proj_abc",
  "query": "SELECT device, browser, COUNT(*) AS session_count FROM sessions GROUP BY device, browser ORDER BY session_count DESC",
  "chart_type": "stacked",
  "title": "Sessions by Device and Browser",
  "x_axis": "device",
  "y_axis": ["session_count"],
  "group_by": "browser"
}

Funnel Charts

Funnel charts measure step-by-step user conversion. The SQL is auto-generated from steps, so query must be the placeholder "SELECT 1". At least 2 steps are required.

The `FunnelStep` Object

Each step in the steps array has the following shape:

{
  "type": "event | track | decoded_log",
  "event": "<event name>",
  "<propertyKey>": { "op": "<operator>", "value": "<value>" }
}

Field	Type	Required	Description
`type`	string	Yes	`event` - built-in events (page, connect, transaction); `track` - custom tracked events; `decoded_log` - decoded smart-contract events
`event`	string	Yes	Event name (e.g. `page`, `connect`, `transaction`)
`<propertyKey>`	`StepFilterCondition`	No	One or more property filters. Any extra key on the step object is treated as a filter. Standard columns (`device`, `browser`, `os`, `location`, `referrer`, `ref`, `utm_*`) are filtered directly; all other keys are extracted from `properties` via `JSONExtractString`

Filter Operators (`StepFilterCondition`)

{ "op": "<operator>", "value": "<value>" }

`op`	SQL equivalent	Notes
`equals`	`= 'value'`	Exact match
`notEquals`	`!= 'value'`	Inverse match
`in`	`IN (...)`	Pipe-delimited value: `"metamask\|rainbow\|coinbase"`
`notIn`	`NOT IN (...)`	Pipe-delimited value
`gt`	`> value`	Numeric comparison
`gte`	`>= value`	Numeric comparison
`lt`	`< value`	Numeric comparison
`lte`	`<= value`	Numeric comparison
`startsWith`	`startsWith(col, 'v')`	String prefix
`endsWith`	`endsWith(col, 'v')`	String suffix
`includes`	`like '%v%'`	Substring match

For in and notIn, join multiple values with a pipe |. Escape a literal pipe with \| and a literal backslash with \\.

`settings` for Funnel Charts

Field	Type	Default	Description
`funnelType`	`"closed"` \| `"open"`	`"closed"`	`closed` - strict ordering, no events between steps; `open` - ordered but other events may occur between steps
`conversionWindow`	`ConversionWindow`	2 days	Max time from Step 1 for a user to complete all steps
`breakdown`	string	-	Split each funnel bar by this dimension

`ConversionWindow`

{ "value": 7, "unit": "day" }

unit must be one of: hour · day · week (7 days).

`breakdown` values

Funnel Examples

Basic 3-step closed funnel

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel",
  "steps": [
    { "type": "event", "event": "page" },
    { "type": "event", "event": "connect" },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 7, "unit": "day" }
  }
}

With per-step property filters

Filter step 2 to MetaMask wallet connections on Ethereum mainnet:

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "MetaMask Conversion Funnel",
  "steps": [
    { "type": "event", "event": "page" },
    {
      "type": "event",
      "event": "connect",
      "rdns": { "op": "equals", "value": "io.metamask" },
      "chain_id": { "op": "equals", "value": "1" }
    },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 7, "unit": "day" }
  }
}

With breakdown by device

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Onboarding Funnel by Device",
  "steps": [
    { "type": "event", "event": "page" },
    { "type": "event", "event": "connect" },
    { "type": "event", "event": "signature" }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": { "value": 30, "unit": "day" },
    "breakdown": "device"
  }
}

Open funnel with multi-value `in` filter

{
  "projectId": "proj_abc",
  "query": "SELECT 1",
  "chart_type": "funnel",
  "title": "Mobile Onboarding Funnel",
  "steps": [
    {
      "type": "event",
      "event": "page",
      "device": { "op": "equals", "value": "mobile" }
    },
    {
      "type": "event",
      "event": "connect",
      "provider_name": { "op": "in", "value": "metamask|rainbow|coinbase" }
    },
    { "type": "event", "event": "transaction" }
  ],
  "settings": {
    "funnelType": "open",
    "conversionWindow": { "value": 30, "unit": "day" },
    "breakdown": "device"
  }
}

User Paths Charts

Visualize how users navigate your app after a starting event. settings.startStep is required.

`settings` for User Paths Charts

Field	Type	Default	Description
`startStep`	`FunnelStep`	-	Required. Event where the flow begins
`endStep`	`FunnelStep` \| `null`	`null`	Optional ending event. `null` = open-ended
`maxSteps`	integer (2 to 5)	`3`	Max steps to show in the flow. Values above 5 are clamped to 5
`nodesPerStep`	integer (2 to 8)	`5`	Max unique event nodes per step. Values above 8 are clamped to 8
`conversionWindow`	`ConversionWindow`	2 weeks	Time window to group the flow
`filters`	string	-	JSON-encoded string of additional path filters

{
  "projectId": "proj_abc",
  "query": "SELECT anonymous_id, type AS event, timestamp FROM events WHERE timestamp >= today() - INTERVAL 30 DAY ORDER BY anonymous_id, timestamp",
  "chart_type": "user_paths",
  "title": "Post-Connect User Flow",
  "settings": {
    "startStep": { "type": "event", "event": "connect" },
    "endStep": { "type": "event", "event": "transaction" },
    "maxSteps": 5,
    "conversionWindow": { "value": 2, "unit": "week" }
  }
}

Retention Charts

Measures how often users return over time. The query field is not used - pass "" or omit it.

`settings` for Retention Charts

Field	Type	Description
`retentionFilter`	`FunnelStep` \| `null`	Event that qualifies a returning visit as “retained”. `null` = any event counts
`retentionUserFilters`	`RetentionUserFilter[]`	User-segment filters that narrow the retention cohort

Each RetentionUserFilter:

Field	Type	Description
`field`	string	User property (e.g. `device`, `browser`, `os`, `utm_source`, `location`)
`op`	string	Comparison operator (same set as `StepFilterCondition.op`)
`value`	string \| number	Value to compare against

{
  "projectId": "proj_abc",
  "query": "",
  "chart_type": "retention",
  "title": "Weekly Retention - Desktop Users",
  "settings": {
    "retentionFilter": { "type": "event", "event": "transaction" },
    "retentionUserFilters": [
      { "field": "device", "op": "equals", "value": "desktop" },
      { "field": "utm_source", "op": "notEquals", "value": "direct" }
    ]
  }
}

For all-user retention with no filters, omit settings:

{
  "projectId": "proj_abc",
  "query": "",
  "chart_type": "retention",
  "title": "Overall Retention"
}

Validation Reference

Chart Type	Validation Rule
`table`	`query` must execute successfully
`number`	`query` must return exactly 1 row × 1 column
`bar`	`x_axis` required; `y_axis` requires ≥ 1 element
`line`	`x_axis` required; `y_axis` requires ≥ 1 element
`pie`	`y_axis` requires exactly 1 element
`stacked`	`x_axis` required; `y_axis` requires exactly 1 element; `group_by` required
`funnel`	`steps` requires ≥ 2 `FunnelStep` objects; `query` must be `"SELECT 1"` or any valid SQL
`user_paths`	`settings.startStep` required; `query` must execute and return data in the expected user-path format (columns: user identifier, event name, timestamp)
`retention`	No query validation - `query` is ignored

Response

201 Created - returns the full chart object.

{
  "id": "chart_1a2b3c4d",
  "chart_type": "table",
  "title": "Recent Events",
  "description": null,
  "query": "SELECT * FROM events ORDER BY timestamp DESC LIMIT 10",
  "project_id": "proj_abc",
  "board_id": "board_xyz"
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Funnel chart must have at least 2 steps",
    "doc_url": "https://docs.formo.so/api/errors#bad_request"
  }
}

Authorizations

Authorization

string

header

required

Workspace API key (e.g. formo_xxx). Create one in the Formo dashboard under Team Settings > API Keys.

Path Parameters

boardId

string

required

Body

application/json

Request body for creating a chart.

projectId

string

required

Project the chart belongs to.

chart_type

enum<string>

required

Visualization type. Determines which other fields are required:

`chart_type`	Extra required fields
`table`	`query`
`number`	`query` (must return 1 row × 1 column)
`bar`	`query`, `x_axis`, `y_axis` (≥ 1)
`line`	`query`, `x_axis`, `y_axis` (≥ 1)
`area`	`query`, `x_axis`, `y_axis` (≥ 1; exactly 1 if `group_by` set)
`pie`	`query`, `y_axis` (exactly 1)
`stacked`	`query`, `x_axis`, `y_axis` (exactly 1), `group_by`
`funnel`	`steps` (≥ 2), `query` placeholder `"SELECT 1"`
`user_paths`	`query`, `settings.startStep`
`retention`	none (`query` ignored)

Available options:

table,

number,

funnel,

bar,

line,

area,

pie,

stacked,

user_paths,

retention

title

string

required

Display name shown on the chart and board.

Minimum string length: 1

query

string

SQL query that powers the chart.

funnel: pass "SELECT 1"; the actual query is auto-generated from steps.
retention: can be omitted or pass ""; data is fetched automatically.
All other types: required; must be a valid SQL string.

Minimum string length: 1

description

string

Optional description.

x_axis

string

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

y_axis

string[]

Column name(s) used as Y axis metrics.

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

group_by

string

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

steps

object[]

Ordered list of funnel steps. Required for funnel (minimum 2 steps).

Each element is a FunnelStep; add property filters as extra keys on the step object (e.g. "rdns": { "op": "equals", "value": "io.metamask" }).

Minimum array length: 2

Show child attributes

settings

object

Chart-type-specific configuration. The fields that apply depend on chart_type:

funnel: funnelType, conversionWindow, breakdown
user_paths: startStep, endStep, maxSteps, nodesPerStep, conversionWindow, filters
retention: retentionFilter, retentionUserFilters, retentionSignalType, retentionLabelSignal

All fields are optional at the schema level; see per-type validation rules for which are functionally required.

Show child attributes

Response

201 - application/json

Chart created

A saved chart attached to a board.

string

required

chart_type

enum<string>

required

Visualization type.

Available options:

table,

number,

funnel,

bar,

line,

area,

pie,

stacked,

user_paths,

retention

title

string

required

query

string

required

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

project_id

string

required

board_id

string

required

description

string | null

x_axis

string | null

Column used as the X axis.

y_axis

string[] | null

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

group_by

string | null

Column used to group/stack series.

steps

object[] | null

Ordered list of funnel steps. Only present when chart_type is funnel.

Show child attributes

settings

object | null

Type-specific configuration. See ChartSettings for all fields.

Show child attributes

Get Chart

Update Chart

​Overview

​Request Fields

​Chart Types

​table

​number

​bar, line, and area

​pie

​stacked

​Funnel Charts

​The FunnelStep Object

​Filter Operators (StepFilterCondition)

​settings for Funnel Charts

​ConversionWindow

​breakdown values

​Funnel Examples

​Basic 3-step closed funnel

​With per-step property filters

​With breakdown by device

​Open funnel with multi-value in filter

​User Paths Charts

​settings for User Paths Charts

​Retention Charts

​settings for Retention Charts

​Validation Reference

​Response

​Overview

​Request Fields

​Chart Types

​table

​number

​bar, line, and area

​pie

​stacked

​Funnel Charts

​The FunnelStep Object

​Filter Operators (StepFilterCondition)

​settings for Funnel Charts

​ConversionWindow

​breakdown values

​Funnel Examples

​Basic 3-step closed funnel

​With per-step property filters

​With breakdown by device

​Open funnel with multi-value in filter

​User Paths Charts

​settings for User Paths Charts

​Retention Charts

​settings for Retention Charts

​Validation Reference

​Response

Authorizations

Path Parameters

Body

Response

Overview

Request Fields

Chart Types

`table`

`number`

`bar`, `line`, and `area`

`pie`

`stacked`

Funnel Charts

The `FunnelStep` Object

Filter Operators (`StepFilterCondition`)

`settings` for Funnel Charts

`ConversionWindow`

`breakdown` values

Funnel Examples

Basic 3-step closed funnel

With per-step property filters

With breakdown by device

Open funnel with multi-value `in` filter

User Paths Charts

`settings` for User Paths Charts

Retention Charts

`settings` for Retention Charts

Validation Reference

Response

Overview

Request Fields

Chart Types

`table`

`number`

`bar`, `line`, and `area`

`pie`

`stacked`

Funnel Charts

The `FunnelStep` Object

Filter Operators (`StepFilterCondition`)

`settings` for Funnel Charts

`ConversionWindow`

`breakdown` values

Funnel Examples

Basic 3-step closed funnel

With per-step property filters

With breakdown by device

Open funnel with multi-value `in` filter

User Paths Charts

`settings` for User Paths Charts

Retention Charts

`settings` for Retention Charts

Validation Reference

Response