Skip to main content
POST
Add a widget to a report

Authorizations

Authorization
string
header
required

An API key, sent as Authorization: Bearer stfy_live_…. See Authentication for how to get one and which scopes it needs.

Path Parameters

report_id
string
required

The report's id, from GET /v1/reports

Body

application/json
title
string
required
Required string length: 1 - 255
type
enum<string>
required
Available options:
metric,
bar_chart,
line_chart,
area_chart,
pie_chart,
scatter_chart,
table,
text
chart
ReportChartInput · object | null

For a chart, metric or table: its display settings

markdown
boolean | null

For a text widget: show text as Markdown (default true)

position
ReportWidgetPositionInput · object | null

Where it sits on the report's grid (12 columns wide). Left out or null, it goes at the left below the lowest widget, sized as the reports page sizes a new one (metric 3x2, bar_chart 6x4, line_chart 6x4, area_chart 6x4, pie_chart 4x4, scatter_chart 6x4, table 12x4, text 4x2)

sql
string | null

For a chart, metric or table: one SELECT over the report views, as POST /v1/reports/query takes it (WITH queries are fine), except that a UNION, INTERSECT or EXCEPT can't be the whole statement (one can be in a subquery). On the reports page, a report's filter on a view's column is added to the outer SELECT's WHERE, so on a LEFT JOINed view it also drops the rows the join didn't match. It reaches the view through the outer FROM: the view itself, or a WITH query or subquery whose SELECT returns the column under the same name or with a bare . The widget skips a filter it can't reach that way, such as through a renamed or aggregated column, a v., or a UNION, and one on a view the outer FROM reads twice. There, a viewer who sees only their own accounts reads every report view in it limited to those accounts, wherever it is named (people_internal_view, your workspace's own people, belongs to no account and isn't limited). What is saved is the checked statement, as POST /v1/reports/query returns it in sql: without comments or your workspace's schema name, with some spellings normalized

Required string length: 1 - 20000
text
string | null

For a text widget: its content

Maximum string length: 20000

Response

201 - application/json

Successful Response

built_with
enum<string>
required

sql (it runs SQL: sql holds it), builder (made with the visual query builder; the API doesn't return its query), or text (a text widget: text holds it)

Available options:
sql,
builder,
text
chart
ReportChart · object
required

A widget's display settings, as the reports page stores them.

id
string
required
position
ReportWidgetPosition · object | null
required

Where it sits on the report's grid; null if what's stored can't be read

title
string
required
type
string
required

metric, bar_chart, line_chart, area_chart, pie_chart, scatter_chart, table or text

markdown
boolean | null

A text widget's Markdown option: true shows text as Markdown, false as plain text

sql
string | null

The widget's SQL as saved in the app: it may have comments or your workspace's schema name. On the reports page it runs with the report's filters and the viewer's scope added, under the app's own checks, so POST /v1/reports/query may refuse it or return different rows

text
string | null

A text widget's content. The app shows it as Markdown when the widget's Markdown option is on (new text widgets have it on), otherwise as plain text