Add data widget
add_data_widgetAdd 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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
TableJSON 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. A failure comes back as an error result instead. |