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>",
  "chart_type": "table",
  "title": "<string>",
  "query": "<string>",
  "project_id": "<string>",
  "board_id": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 2,
      "unit": "hour"
    },
    "breakdown": "device",
    "anchors": [
      {
        "type": "event",
        "event": "<string>",
        "events": [
          {
            "type": "event",
            "event": "<string>",
            "filters": [
              {
                "field": "<string>",
                "op": "eq",
                "value": "<string>"
              }
            ]
          }
        ],
        "filters": [
          {
            "field": "<string>",
            "op": "eq",
            "value": "<string>"
          }
        ]
      }
    ],
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    },
    "entryFilter": {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    },
    "retentionUserFilters": [
      {
        "field": "<string>",
        "op": "eq",
        "value": "<string>"
      }
    ],
    "retentionSignalType": "event",
    "retentionLabelSignal": {
      "field": "<string>",
      "op": "gt",
      "value": "<string>",
      "chain_id": ""
    },
    "retentionCohortLabelFilters": [
      {
        "field": "<string>",
        "op": "eq",
        "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>",
  "chart_type": "table",
  "title": "<string>",
  "query": "<string>",
  "project_id": "<string>",
  "board_id": "<string>",
  "description": "<string>",
  "x_axis": "<string>",
  "y_axis": [
    "<string>"
  ],
  "group_by": "<string>",
  "steps": [
    {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    }
  ],
  "settings": {
    "funnelType": "closed",
    "conversionWindow": {
      "value": 2,
      "unit": "hour"
    },
    "breakdown": "device",
    "anchors": [
      {
        "type": "event",
        "event": "<string>",
        "events": [
          {
            "type": "event",
            "event": "<string>",
            "filters": [
              {
                "field": "<string>",
                "op": "eq",
                "value": "<string>"
              }
            ]
          }
        ],
        "filters": [
          {
            "field": "<string>",
            "op": "eq",
            "value": "<string>"
          }
        ]
      }
    ],
    "maxSteps": 3,
    "nodesPerStep": 5,
    "filters": "<string>",
    "retentionFilter": {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    },
    "entryFilter": {
      "type": "event",
      "event": "<string>",
      "events": [
        {
          "type": "event",
          "event": "<string>",
          "filters": [
            {
              "field": "<string>",
              "op": "eq",
              "value": "<string>"
            }
          ]
        }
      ],
      "filters": [
        {
          "field": "<string>",
          "op": "eq",
          "value": "<string>"
        }
      ]
    },
    "retentionUserFilters": [
      {
        "field": "<string>",
        "op": "eq",
        "value": "<string>"
      }
    ],
    "retentionSignalType": "event",
    "retentionLabelSignal": {
      "field": "<string>",
      "op": "gt",
      "value": "<string>",
      "chain_id": ""
    },
    "retentionCohortLabelFilters": [
      {
        "field": "<string>",
        "op": "eq",
        "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 derive SQL from steps and accept "SELECT 1" as the placeholder. User Paths charts derive SQL from settings.anchors, so omit query.

Request Fields

Field	Type	Required	Description
`projectId`	string	Yes	Project the chart belongs to
`query`	string	Conditional	SQL query. Omit for `user_paths` and `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>",
  "filters": [{ "field": "<property>", "op": "<op>", "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`)
`filters`	`StepFilterCondition[]`	No	Canonical `{field, op, value}` property filters. Standard columns are filtered directly; other fields are extracted from event `properties`.

Filter Operators (`StepFilterCondition`)

{ "field": "<property>", "op": "<op>", "value": "<value>" }

`op`	SQL equivalent	Notes
`eq`	`= 'value'`	Exact match
`neq`	`!= 'value'`	Inverse match
`in`	`IN (...)`	Pipe-delimited value: `"metamask\|rainbow\|coinbase"`
`nin`	`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
`contains`	`like '%v%'`	Substring match
`notEmpty`	`col != ''`	Value-less existence check; `value` is ignored
`isEmpty`	`col = ''`	Value-less existence check; `value` is ignored

For in and nin, join multiple values with a pipe |. Escape a literal pipe with \| and a literal backslash with \\. The legacy numeric long forms (greater, greaterOrEqual, less, lessOrEqual) are retired and rejected with a 400 naming the token. Send gt / gte / lt / lte. notEmpty and isEmpty are rejected on the numeric event columns volume / revenue / points.

`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",
      "filters": [
        { "field": "rdns", "op": "eq", "value": "io.metamask" },
        { "field": "chain_id", "op": "eq", "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",
      "filters": [{ "field": "device", "op": "eq", "value": "mobile" }]
    },
    {
      "type": "event",
      "event": "connect",
      "filters": [
        {
          "field": "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 through an ordered list of path anchors. settings.anchors requires at least one entry. One anchor produces an open-ended exploration; two or more constrain the path in order.

`settings` for User Paths Charts

Field	Type	Default	Description
`anchors`	`FunnelStep[]`	-	Required. Ordered path anchors; one entry is 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",
  "chart_type": "user_paths",
  "title": "Post-Connect User Flow",
  "settings": {
    "anchors": [
      { "type": "event", "event": "connect" },
      { "type": "event", "event": "transaction" }
    ],
    "maxSteps": 5,
    "conversionWindow": { "value": 2, "unit": "week" }
  }
}

Retention Charts

Measures how often users return over time. Omit the query field; retention data is fetched automatically.

`settings` for Retention Charts

Field	Type	Description
`entryFilter`	`FunnelStep` \| `null`	Required key. Event that enters the cohort; `null` means any event
`retentionFilter`	`FunnelStep` \| `null`	Event that qualifies a return as “retained”; `null` means any event
`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`, minus the substring operators `startsWith` / `endsWith` / `contains`)
`value`	string \| number	Value to compare against

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

For all-user retention with no event filters, explicitly set both event filters to null:

{
  "projectId": "proj_abc",
  "chart_type": "retention",
  "title": "Overall Retention",
  "settings": {
    "entryFilter": null,
    "retentionFilter": null
  }
}

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.anchors` requires at least one entry; the query is generated from the anchors
`retention`	`settings.entryFilter` key is required; omit `query`

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. Omit for `user_paths` and `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>",
  "filters": [{ "field": "<property>", "op": "<op>", "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`)
`filters`	`StepFilterCondition[]`	No	Canonical `{field, op, value}` property filters. Standard columns are filtered directly; other fields are extracted from event `properties`.

Filter Operators (`StepFilterCondition`)

{ "field": "<property>", "op": "<op>", "value": "<value>" }

`op`	SQL equivalent	Notes
`eq`	`= 'value'`	Exact match
`neq`	`!= 'value'`	Inverse match
`in`	`IN (...)`	Pipe-delimited value: `"metamask\|rainbow\|coinbase"`
`nin`	`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
`contains`	`like '%v%'`	Substring match
`notEmpty`	`col != ''`	Value-less existence check; `value` is ignored
`isEmpty`	`col = ''`	Value-less existence check; `value` is ignored

`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",
      "filters": [
        { "field": "rdns", "op": "eq", "value": "io.metamask" },
        { "field": "chain_id", "op": "eq", "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",
      "filters": [{ "field": "device", "op": "eq", "value": "mobile" }]
    },
    {
      "type": "event",
      "event": "connect",
      "filters": [
        {
          "field": "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

`settings` for User Paths Charts

Field	Type	Default	Description
`anchors`	`FunnelStep[]`	-	Required. Ordered path anchors; one entry is 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",
  "chart_type": "user_paths",
  "title": "Post-Connect User Flow",
  "settings": {
    "anchors": [
      { "type": "event", "event": "connect" },
      { "type": "event", "event": "transaction" }
    ],
    "maxSteps": 5,
    "conversionWindow": { "value": 2, "unit": "week" }
  }
}

Retention Charts

Measures how often users return over time. Omit the query field; retention data is fetched automatically.

`settings` for Retention Charts

Field	Type	Description
`entryFilter`	`FunnelStep` \| `null`	Required key. Event that enters the cohort; `null` means any event
`retentionFilter`	`FunnelStep` \| `null`	Event that qualifies a return as “retained”; `null` means any event
`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`, minus the substring operators `startsWith` / `endsWith` / `contains`)
`value`	string \| number	Value to compare against

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

For all-user retention with no event filters, explicitly set both event filters to null:

{
  "projectId": "proj_abc",
  "chart_type": "retention",
  "title": "Overall Retention",
  "settings": {
    "entryFilter": null,
    "retentionFilter": null
  }
}

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.anchors` requires at least one entry; the query is generated from the anchors
`retention`	`settings.entryFilter` key is required; omit `query`

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.

Headers

Idempotency-Key

string

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.

Maximum string length: 255

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`	`settings.anchors` (≥ 1); query is generated
`retention`	`settings.entryFilter` (key required; `null` means any event)

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

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 predicates in its canonical filters array (e.g. "filters": [{ "field": "rdns", "op": "eq", "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: anchors, maxSteps, nodesPerStep, conversionWindow, filters
retention: entryFilter, retentionFilter, retentionUserFilters, retentionSignalType, retentionLabelSignal

Fields are optional at the schema level except where the selected chart type requires them. User Paths require at least one anchors entry. Retention requests must explicitly include entryFilter; use null for any event.

Show child attributes

Response

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

​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

Headers

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