Dreamdata

Return the entity list behind a saved report metric value (a drilldown). This is not the same as `run_saved_report`'s `output_type=contact_list`: `run_saved_report` returns a report-defined view; this tool returns the entities (companies, contacts, deals, stages, or events) that contribute to a specific metric's value. For report-defined slices, use `run_saved_report`. On the initial call, provide `report_id`, `output_type`, and `metric_id`. `output_type` selects which list to return: `company_list`, `contact_list`, `deal_list`, `stage_list`, or `event_list`. Do not guess the pair: run the report first (`run_saved_report` with no `output_type`, or `report_builder_run_config`) and read its `drilldown_metrics`, which lists each drillable metric with the one `output_type` it supports. Optionally pass `segment_by_values` to filter by segment properties. The response includes `next_page_token`; pass it back as `page_token` to fetch subsequent pages, with the same `slug` as the call that returned it (omit all other args when paginating).

list_report_metric_drilldown_entities

List all saved reports visible to the authenticated user. Calls GET /v1/content-list/view?viewAll=true and returns a trimmed catalog: each item carries just the fields needed to identify a report (id, name, description, folder, visibility, author, timestamps). Pass the returned `id` to the `run_saved_report` tool to run one. Dashboards and non-report items are filtered out.

list_saved_reports

Get the building blocks for a chosen analysis (step 3 — your source of truth). Returns: - `sections`: the report description, the metrics, the filter and segment properties (with descriptions, operators and sample values) and the config schema, each item's ids grouped under `internal`. The config schema names the attribution models this account can use. - `metric_groups`: every metric group in the account — `{metric_group, label, metric_count}`. Use it to pick a `metric_group` for a follow-up call; it is never scoped away. - `stage_filter_properties`: the ids that populate `metrics.stageMetrics.<model>.filterBy`, keyed by metric group — returned ONLY when `metric_group` names one stage group exactly. Otherwise you get `stage_filter_properties_note` instead; they are omitted because each stage model repeats the same properties under different hashed ids, which is what makes this response explode on accounts with many stage models. Build the report config using ONLY the metric and property IDs returned here — never invent IDs from labels. IDs are opaque hashes (e.g. `p_y54efhqz2gmhgdf`, `m_zfp2zcnivsdzqvx`) — copy them exactly as returned. Never construct or guess IDs; they are not derivable from labels or any pattern. `metric_group` scoping: pass an **exact** group id from `metric_groups` (e.g. `"activityCountMetrics"` or `"stageMetrics.stage_model_abc"`) to cut the response down and to get that stage's filter properties. The `"stageMetrics"` family shorthand keeps every stage model's metrics, so it barely reduces size and never returns stage filter properties — reach for one exact stage group per call instead (repeat the call per stage if a report spans several).

report_builder_get_components

List the analysis types a report can be built on. Each entry carries a `summary` and `selection_guidance` to help choose between neighbouring types. This is step 1 of the report-building flow; `report_builder_start` returns the same list plus the full workflow.

report_builder_list_analysis_types

List the most common values for a filter/segment property (browse). Use when the user wants to see what's available ("what channels can I filter on?"). Returns the most frequent values. If the user already named a value, use `report_builder_search_property_values` instead. The result is a single page. When more values exist, `totals.has_more` says so (with `totals.total`). Do not try to page through them: tell the user roughly how many there are and search for what they are after.

report_builder_list_property_values

List the analysis subjects available for an analysis type (step 2). The subject narrows what the analysis is about (e.g. which pipeline stage, or all contacts). Pick one, then fetch its details.

report_builder_list_subjects

Turn a named calendar period into a report `time` filter (reads no account data). Use for a specific month ("May 2025" → year=2025, month=5), quarter ("Q1 2024" → year=2024, quarter=1), or whole year ("2023" → year=2023). Pass `month` OR `quarter`, never both. Returns a `value` shortcut or a frozen `start`/`end` pair to copy into `config.time`, plus an `aggregation_hint`. Never compute report dates yourself — always use this.

report_builder_resolve_calendar_period

Turn a rolling window into a report `time` filter (reads no account data). Use for "last N days/weeks/months/years" (e.g. n=45, unit="days"). When the window matches a live shortcut exactly it returns a `value` token (put it in `time.value`); otherwise it returns a frozen `start`/`end` pair. Includes an `aggregation_hint`. Never compute report dates yourself — always use this.

report_builder_resolve_rolling_window

Validate and run a report config; returns results or a fixable error (step 6). There is no separate validation step — this tool validates the config before running it. Omit `output_type` to get the full payload (and a `supported_output_types` field listing the slices this report can produce); or name a single slice (e.g. `summary_table`, `time_series`, `company_list`) to fetch just that view — call once without it first to learn which slices are supported. On an invalid config it raises with the API's structured validation errors in the message; read them, fix the config using the metric and property IDs from `report_builder_get_components`, and call this again. Results are paged. A single-slice response carries `nextPageToken`; the full payload carries `nextPageTokens` keyed by wire-shape name (`summaryTable`, `timeSeries`). When a token is non-null there are more rows: pass it back as `page_token` to fetch the next page, together with the same `slug` as the call that returned it, and omit every other argument — including `config`, which the token already encodes, so never re-send it just to page. A paginating call returns `{rows, next_page_token, total_rows}`; keep passing each `next_page_token` until it comes back null. Page size is fixed when the first token is issued and cannot be changed while paging. Money amounts (columns with `unit: "currency"`, or metrics whose `displaySymbol` is `"currency"`) are in the account's own currency, which the result does not name. To write one with a symbol or code, call `get_account_currency` first; never guess a currency.

report_builder_run_config

Search a property's values by case-insensitive substring (validate). Use this before writing any user-named value into a filter (e.g. "paid social" → search="paid social") to confirm the value exists and catch spelling near-misses. Returns only matching values; the match runs over every value of the property, not just the most frequent ones. The result is a single page. When more values match than were returned, `totals.has_more` says so (with `totals.total`): ask the user for a more specific term rather than paging.

report_builder_search_property_values

Begin building a Dreamdata report. Call this first. Returns the ordered report-building workflow plus the analysis types you can build on (each with selection guidance for choosing between them). Walk the steps in order — every subsequent tool's response tells you what to call next. Use this whenever a user wants to create, build, or set up a new report from scratch (to run an existing saved report, use `run_saved_report` instead).

report_builder_start

Run an audience definition and return matching contacts or companies. `config` is a list of groups. Conditions inside a group are OR'd, while groups are AND'd. Each condition is an object with a `conditionType` (`property`, `event`, `stage`, or `signal`) plus camelCase structural fields (`propertySource`, `propertyObject`, …); the `property` value itself is an account-specific key returned by `list_audience_filter_properties`. Each condition's `propertyType` is resolved automatically from that catalog, so it can be omitted. Condition `values` are always strings, including numbers (e.g. ["0.5"]). For the full condition structure — every conditionType's fields, the operator and time-shortcut enums, and nested filterBy / andThen — call `describe_audience_config_schema`. Use `list_audience_filter_properties` to discover account-specific properties and `list_audience_filter_values` to enumerate valid values. Prefer the operators a property's `allowedOperators` lists: they are the ones that make sense for its type, though a few others are also accepted. Date and datetime properties are the strict case — only `before`/`after`, each needing one timestamp value, with no null check. Event conditions select the event with `property="event"` and the event name in `values` (`any_event` matches any event); use `list_audience_filter_values` with `property="event"` to list them. An event condition may instead filter directly on an event attribute such as `url_clean`. `eventType` defaults to `at_least` and `count` to "1", so "performed this event" needs neither. Set `count` for a specific number, and give it explicitly with `eventType="at_most"` or `"only"` — neither has a safe default. Use `eventType="only"` with `count="0"` for "never performed". `count` may be written as a number or a string. A chain step in `andThen` takes no `count`, and a `signal` condition takes no `eventType`. In an `andThen` chain, order is taken from the list itself — the steps run in the order given, and you never set a position field. A config from `get_audience_definition` can be passed as-is: the query builder's bookkeeping (`id`, `ui_value`/`ui_label`, `filterBy: false`, and a `dateRange` materialized beside a time shortcut) is ignored. A saved `custom_period` window is the one exception — its `dateRange` is not part of this contract and is reported rather than silently reinterpreted. `sort_by` takes a result column alias, not a property key. For companies: companyId, name, website, country, industry, accountOwnerName, numberOfEmployees, contacts, channels, sessions, lastSeen, linkedinUrl, isNew, engagementScore, engagementScoreTrend, activityTrend, sourceSystem. For contacts: contactId, email, name, title, userCountry, lastSeen, companies, sourceSystem. Stage conditions match on the `stage_name` property; valid stage names are the `revenueModel` values of the `stages` groups returned by `list_audience_filter_properties`. Pagination: `audiences.totalRowCount` is the full match count, of which each response returns one `page_size` slice. To read the next slice, pass the response's `audiences.pageToken` back as `page_token` together with the same `audience_type` and `config`, and keep going until a response has no `pageToken`. Treat the token as opaque — it also identifies the query results it pages through, so it cannot be edited, split, swapped with a token from another tool, or reused once those results expire (about 24 hours). Examples: - Companies in Fintech industry: [{"conditions": [{"conditionType": "property", "propertySource": "dreamdata", "propertyObject": "companies", "property": "industry", "operator": "equals", "values": ["Fintech"]}]}] - Companies with a 30-day engagement score above 0.5: [{"conditions": [{"conditionType": "property", "propertySource": "dreamdata", "propertyObject": "companies", "property": "engagement_score_30_days", "operator": "greater_than", "values": ["0.5"]}]}] - Contacts who performed `page_view` at least 3 times in the last 30 days: [{"conditions": [{"conditionType": "event", "propertySource": "dreamdata", "propertyObject": "events", "property": "event", "operator": "equals", "values": ["page_view"], "eventType": "at_least", "count": "3", "time": {"conditionTimeType": "shortcut", "value": "last_30_days"}}]}] - Contacts with any event on a given URL in the last 30 days (`any_event` matches any event name; `filterBy` narrows it): [{"conditions": [{"conditionType": "event", "propertySource": "dreamdata", "propertyObject": "events", "property": "event", "operator": "equals", "values": ["any_event"], "eventType": "at_least", "count": "1", "time": {"conditionTimeType": "shortcut", "value": "last_30_days"}, "filterBy": [{"propertySource": "dreamdata", "propertyObject": "events", "property": "url_clean", "operator": "contains", "values": ["/pricing"]}]}]}] - Companies that reached the MQL stage in the last 90 days: [{"conditions": [{"conditionType": "stage", "propertySource": "dreamdata", "propertyObject": "stages", "property": "stage_name", "operator": "equals", "values": ["MQL"], "stageType": "reached", "time": {"conditionTimeType": "shortcut", "value": "last_90_days"}}]}]

run_audience_query

Generate a saved report on behalf of the authenticated user. `output_type` selects a report-defined view (the metric cards, summary table, or list slices the report itself produces). Omit it to fetch the full payload — that response includes a `supported_output_types` field listing exactly which slice names this report accepts, so call it first when you don't yet know what's available. It also includes `drilldown_metrics`: the `(metric_id, output_type)` pairs `list_report_metric_drilldown_entities` will accept for this report. Results are paged. A single-slice response carries `nextPageToken`; the full payload carries `nextPageTokens` keyed by wire-shape name (`summaryTable`, `timeSeries`). When a token is non-null there are more rows: pass it back as `page_token` to fetch the next page, together with the same `slug` as the call that returned it, and omit every other argument — a paginating call resolves nothing from the report and returns `{rows, next_page_token, total_rows}`. Keep passing each response's `next_page_token` until it comes back null. Page size is fixed when the first token is issued and cannot be changed while paging. Money amounts (columns with `unit: "currency"`, or metrics whose `displaySymbol` is `"currency"`) are in the account's own currency, which the result does not name. To write one with a symbol or code, call `get_account_currency` first; never guess a currency. For entities behind a specific metric value (a drilldown), use `list_report_metric_drilldown_entities` instead — its `output_type` names look the same (`contact_list`, etc.) but mean "entities behind this metric," not "report-defined view."

run_saved_report

Run a saved report over a custom date range, without saving any change. Loads the saved report and overrides ONLY its time window with the given absolute range — every other setting (filters, metrics, segmentation, time aggregation) is inherited from the saved report unchanged. The report is run and the full result payload is returned (metrics, summaryTable, timeSeries, nextPageTokens) plus a `supported_output_types` field, unless `output_type` narrows it to a single slice. Nothing is persisted. `start_date` and `end_date` are YYYY-MM-DD and both inclusive; pass the same date as both for a single day. The end must be on or after the start, on or before today, and the start no earlier than 2006-01-01. `output_type` works exactly as it does on `run_saved_report`: omit it for the full payload (which carries `supported_output_types`), or name one slice (e.g. `summary_table`, `time_series`, `company_list`) to fetch just that view. Results are paged. `nextPageTokens` is keyed by wire-shape name (`summaryTable`, `timeSeries`); when one of those is non-null there are more rows for that slice. Pass it back as `page_token`, with the same `slug` as the call that returned it and no other argument, to fetch the next page, which returns `{rows, next_page_token, total_rows}`. Keep passing each response's `next_page_token` until it comes back null. Page size is fixed when the first token is issued and cannot be changed while paging. The date range is baked into the token, so do not re-send it when paginating. Money amounts (columns with `unit: "currency"`, or metrics whose `displaySymbol` is `"currency"`) are in the account's own currency, which the result does not name. To write one with a symbol or code, call `get_account_currency` first; never guess a currency. To run a report over its own saved date range, use `run_saved_report` instead.

run_saved_report_for_date_range

Save an audience the user built (ONLY on explicit user request). NEVER call this unless the user has explicitly asked to save the audience — saving writes to their Dreamdata account, where the audience appears in the Audience Hub for everyone on the account and can be synced to ad platforms. Pass the same `audience_type`, `config` and `include_anonymous_companies` that `run_audience_query` last ran successfully; the server adds the fields the Audience Hub editor needs, so do not add ids or `ui_value` yourself. This always creates a new audience; it never changes an existing one. `name` is 1-65 characters and must not match an existing audience's name; `description` is at most 512 characters. `folder_id` is optional: pass an audience folder id from `list_audiences()["folders"][].id`, or a unique folder name. Report folders are separate and are not accepted. Confirmation protocol: the first call does NOT save — it validates the config by running it, then returns a preview (including the audience's current size) and a `confirmation_token`; a config that cannot run is rejected instead. Show the user the name, description, audience type and folder (when set) and ask whether to save. Only after the user clearly says yes, call again with identical arguments plus that `confirmation_token`. Never invent or reuse a token, and never confirm on the user's behalf.

save_audience

Save a report the user configured (step 7 — ONLY on explicit user request). NEVER call this unless the user has explicitly asked to save the report — saving writes to their Dreamdata account (the report appears in the Analytics Hub for everyone on the account). Pass the exact `config` that `report_builder_run_config` last ran successfully — the server normalizes it to the shape the web app saves (metric display order, default ordering, explicit defaults, bare dates) so the report renders correctly in the UI configurator; do not add those presentation fields yourself. `folder_id` is optional. Prefer the folder UUID from `list_saved_reports()["folders"][].id`. A unique folder name is also accepted and resolved to that UUID. Do not invent folder ids. Confirmation protocol: the first call does NOT save — it validates the config, then returns a preview and a `confirmation_token` (an invalid config is rejected instead). Show the user the name, description, and folder (when set) and ask whether to save. Only after the user clearly says yes, call again with the same arguments plus that `confirmation_token`. Never invent or reuse a token, and never confirm on the user's behalf. (On clients that support elicitation the server asks the user directly instead, and no token is needed.)

report_builder_save_report

Search the Companies view by name and return matching journey records. Calls GET /v1/journeys/companies/paginated and returns a trimmed list of company journey records matching the search query. Each item includes core identity fields, engagement metrics, a 30-day activity trend, and CRM source links. Pass the returned `id` to the `get_company_journey` tool to fetch the full journey detail.

search_companies