Skip to main content

Insight Request Payloads

Field values are sourced per metric-context-mapping.md.

Computing now (brief only)​

now is a field on generate-pulse-insight-brief only — the bundle request's options object rejects it (additionalProperties: false, no now field), so never add now to a bundle request.

To compute it for the brief: now = today minus the largest offset_from_today across the metrics' extension_options (use 0 if absent), formatted YYYY-MM-DD.

Single metric — generate-pulse-metric-value-insight-bundle​

Do not include a now field anywhere in this request. Populate extension_options.allowed_dimensions/allowed_granularities and insights_options.settings from the full definition — empty arrays here cause API errors even though they pass schema validation. If the metric is based on an embedded workbook datasource rather than a published one, add id_type: 'DATASOURCE_ID_TYPE_WORKBOOK_DATASOURCE' under definition.datasource. id_type is bundle-only: a brief's datasource allows only id, so route embedded-datasource metrics to the bundle.

bundleRequest:
bundle_request:
version: 1
options:
output_format: 'OUTPUT_FORMAT_HTML'
time_zone: 'UTC'
language: 'LANGUAGE_EN_US'
locale: 'LOCALE_EN_US'
input:
metadata:
name: <metric definition name>
metric_id: <metric instance ID>
definition_id: <metric definition ID>
metric:
definition: <from specification in full definition; must include datasource, basic_specification, is_running_total>
metric_specification: <from metric instance>
extension_options: <from full definition>
representation_options: <from full definition>
insights_options: <from full definition>
goals: <from metric instance goals, if any; bundle takes goals.target.value>
bundleType: 'detail'

Multiple metrics — generate-pulse-insight-brief​

Build metric_group_context by pairing each metric instance with its full definition. Infer action_type from the question:

Question intentaction_type
"why / what caused / what changed / what's driving / what are the top"ACTION_TYPE_ANSWER
"should I / advise / what are the risks / are we on track / forecast"ACTION_TYPE_ADVISE
"summarize / what is / what's happening / overview / how are we doing / what should I focus on (with no metric named)"ACTION_TYPE_SUMMARIZE

For compound questions, use ACTION_TYPE_ADVISE — it covers the broadest scope. Overviews over subscribed metrics use ACTION_TYPE_SUMMARIZE; use ADVISE only when the user asks what to do.

briefRequest:
language: LANGUAGE_EN_US
locale: LOCALE_EN_US
now: <computed above>
messages:
- role: ROLE_USER
action_type: <inferred above>
content: <user's original question, verbatim>
metric_group_context_resolved: true
metric_group_context: <assembled from Step 3, one entry per metric>

Each metric_group_context entry nests like this:

- metadata: { name, metric_id, definition_id }
metric:
definition: { datasource, basic_specification, is_running_total }
metric_specification: <from metric instance>
extension_options: <from full definition>
representation_options: <from full definition>
insights_options: <from full definition>
goals: { metric_goals: { target: { value } }, datasource_goals: [...] }
# datasource_goals entries require minimum_granularity, benchmark_sentiment_type and name; pass them through as returned, never rebuild them
# viz-state-only metrics (no basic_specification) cannot use the bundle

Group metrics by datasource and send one brief per datasource.

Do not call this tool without a populated metric_group_context.

For multi-turn follow-up, carry the previous answer as a ROLE_ASSISTANT message before the new ROLE_USER turn, and reuse metric_group_context. Every message, including the ROLE_ASSISTANT one, must carry action_type, content, metric_group_context and metric_group_context_resolved, or validation fails.