Oviond

Add data widget

add_data_widget

Add a DATA widget to a page and configure it, applying the same rules as the report builder: the datasource's defaults, the generated name, sort and row limit, and validation of the metric/dimension/advanced combination. Discover ids with datasources → describe_datasource. Returns the new widget_id; the series is fetched in the background, so call get_widget_data with that id to read the numbers. Omit the config to drop in a default widget with demo data and configure it later. Position/size default.

Input Schema

Name	Required	Description
`name`	No	Display name. Omit to use the generated one ("Clicks & Impressions by Date")
`chart`	No	Chart type: table, score (KPI), area, line, bar, column, pie, donut, funnel, or map. 'score' shows a single value, so it takes exactly one metric
`filters`	No	Row filters. Every row needs a field, an operator and a value
`metrics`	No	Metrics to display, e.g. [{ value: "clicks" }] — ids from describe_datasource. Must belong to the chosen data view. Only `value` is required; the server fills the rest
`page_id`	Yes	Page ID the widget will be placed on, from list_pages.
`sort_by`	No	Metric or dimension id to sort rows by. Defaults to the first dimension
`advanced`	No	Datasource-specific settings (Meta attribution, SEM Rush region, Mailchimp audience…). Several datasources require keys here — describe_datasource lists them per data view. Merges with existing settings
`currency`	No	Per-widget currency code override; falls back to the client currency
`client_id`	Yes	Client ID the report belongs to (from list_clients).
`data_view`	No	Datasource data view (from describe_datasource), e.g. ACCOUNT. Changing it clears metrics and dimensions
`row_limit`	No	Rows to keep (default 'all')
`source_id`	Yes	Report ID the widget belongs to (from list_reports).
`date_range`	No	Per-widget date range (overrides the report range) — also set show_custom_date_range
`dimensions`	No	Breakdown dimensions, e.g. [{ value: "DATE" }] — ids from describe_datasource. A widget needs at least one; a dimension flagged `single` must be the only one
`sort_order`	No	Sort direction (default 'asc')
`datasource_id`	No	Datasource alias (from datasources), e.g. gadw. Changing it clears the data view, metrics, dimensions, filters and advanced settings, then applies that datasource's defaults. A datasource the client has not connected renders demo data until the connection is made — connected_datasources shows what is connected. The internal sources take no metrics/dimensions and are configured through `advanced` instead: 'CUSTOM_DATA' (Static Value — advanced.value), 'GOALS' (advanced.goal_id from list_goals), 'CUSTOM_IMPORT' (advanced.custom_data_id from list_custom_data), 'CALCULATION' (a calculated metric id as the single metric)
`show_custom_date_range`	No	Use the widget date_range instead of the report range

Output Schema

Name	Required	Description	Default
`data`	No	The data widget that was added — widget_id, the generated name, and the config as the builder resolved it. The series is fetched in the background; read it with get_widget_data using that widget_id.
`success`	Yes	True when the call succeeded.