`company_install_time_series` next channel

Status: Modified (ID-based filters; country granularity; snake_case params) This tool is on the private next MCP channel for allow-listed orgs. When promoted, this file moves to mcp-tools/company-install-time-series.md.

Get installation intensity time series data for a company's technology usage. Returns monthly intensity values for each product over time — use for trend questions like "How has Cisco's usage of Snowflake changed over the past 2 years?" Identify the company by EITHER company_domain OR hg_id — provide exactly one (supplying both or neither is a validation error).

Integration required: hginsights_v2__data_api Cache schema version: 3 (differs from base — stale cached payloads from the public channel will not be served)

Parameters

Parameter	Type	Required	Default	Description
`company_domain`	`string`	Optional	—	The company domain to look up (e.g. `'cisco.com'`). Provide EITHER `company_domain` OR `hg_id` — exactly one is required. `match_confidence` in the response is 0.90 when identified by domain.
`hg_id`	`string`	Optional	—	The hex HG company id (31–32 alphanumeric chars) from `search_companies`. Provide EITHER `hg_id` OR `company_domain` — exactly one is required. `match_confidence` in the response is 1.0 when identified by `hg_id`.
`product_ids`	`integer[]`	Optional	—	Filter by numeric HG product IDs (integers, e.g. `[26434, 22]`). Resolve IDs with `product_search_and_enrich` first — the upstream filters by integer ID only, so names or slug-style IDs return nothing.
`vendor_ids`	`integer[]`	Optional	—	Filter by numeric HG vendor IDs (integers, e.g. `[376]`). Resolve IDs with `get_vendor_information` first.
`category_ids`	`string[]`	Optional	—	Filter by HG category IDs (strings, e.g. `['cat-crm']`). Resolve IDs with `list_product_categories` first.
`country_codes`	`string[]`	Optional	—	ISO 3166-1 alpha-2 country codes (e.g. `['US', 'GB']`). Use with `granularity='country'` to get per-country intensity breakdowns.
`granularity`	`"global" \| "country"`	Optional	—	`'global'` aggregates intensity across all countries (default upstream behavior). `'country'` returns one row per product per country with `country_code` populated on each product.
`time_range`	`string`	Optional	`"last_24_months"`	Time range for the series: `last_6_months`, `last_12_months`, `last_24_months`, or `last_36_months`. Each option returns N+1 data points because the current incomplete month is appended as a null tail (e.g. `last_6_months` → 7 points).
`max_results`	`integer`	Optional	`10`	Maximum number of products to return (1–50, default 10).

Response Format

{
  "company": {
    "company_id": "3AB6196C…",
    "company_name": "Cisco Systems",
    "match_confidence": 0.90
  },
  "time_range": {
    "start_date": "2024-07",
    "end_date": "2026-08",
    "granularity": "month"
  },
  "products": [
    {
      "product_id": "26434",
      "product_name": "Snowflake",
      "vendor_name": "Snowflake Inc.",
      "category": "Data Warehouse",
      "is_active": true,
      "current_intensity": 4200,
      "intensity_momentum": 120.5,
      "country_code": null,
      "data_points": [
        { "date": "2024-07", "intensity": 28 },
        { "date": "2024-08", "intensity": 29 },
        { "date": "2026-08", "intensity": null }
      ]
    }
  ],
  "credits_consumed": 3,
  "warning": null
}

Field meanings

Field	Meaning
`match_confidence`	1.0 for `hg_id`, 0.90 for domain.
`is_active`	Whether the product was verified within the last 90 days.
`current_intensity`	Aggregate intensity from global install data — not on the 1–31 daily scale.
`intensity_momentum`	Positive = growing, negative = declining; magnitude is meaningful.
`country_code`	Populated when `granularity='country'`; null for global rows.
`data_points[].intensity`	Days the product was detected that month (1–31), null if no detection.
`warning`	Present when filters were provided but no products matched — explains the miss and how to resolve it.

Credits

3 credits per product returned; 0 on empty results.

Example Usage

{
  "tool": "company_install_time_series",
  "parameters": {
    "company_domain": "cisco.com",
    "product_ids": [26434],
    "time_range": "last_12_months"
  }
}

Country breakdown:

{
  "tool": "company_install_time_series",
  "parameters": {
    "company_domain": "cisco.com",
    "country_codes": ["US", "GB"],
    "granularity": "country",
    "time_range": "last_12_months"
  }
}

company_technographic — point-in-time install snapshot; get product_id values from here before filtering.
product_search_and_enrich — resolve product names to numeric product_ids.
get_vendor_information — resolve vendor names to numeric vendor_ids.

Changelog

2026-08-04 — Unified API PR #326 alignment

Availability: live on the private next MCP channel for allow-listed orgs. The public /api/mcp contract is unchanged.

Additive — country breakdown (no action required for existing calls):

country_codes — ISO alpha-2 array; restrict the time series to installs from those countries.
granularity — "global" or "country". At "country" the series is broken out per country; each returned product now carries a country_code field.

The cache version is bumped by 2 vs the v1 twin; the new params participate in the cache key.

2026-07-31 — Breaking: params renamed to snake_case

Availability: live on the private next MCP channel for allow-listed orgs. The public /api/mcp contract is unchanged.

	Before (on `next`)	After
Domain param	`companyDomain`	`company_domain`
ID param	`hgId`	`hg_id`
Product filter	`productIds`	`product_ids`
Vendor filter	`vendorIds`	`vendor_ids`
Category filter	`categoryIds`	`category_ids`
Date range	`timeRange`	`time_range`
Pagination	`maxResults`	`max_results`

Output: productsReturned → products_returned. All upstream passthrough row fields (already snake_case) are unchanged.

2026-07-30 — Breaking: identifier and filter inputs changed (ID-based)

Why this changed: filters are now ID-based (numeric IDs) to match the official HG Insights API, and both company_domain and hg_id are accepted as company identifiers (exactly one required).

Breaking change

	Before	After
Company identifier	`companyDomain` only (required)	exactly one of `company_domain` or `hg_id` (required)
Product filter	`products` (names) and `productIds` (string IDs)	`product_ids` — numeric IDs (integers)
Vendor filter	`vendors` (names)	`vendor_ids` — numeric IDs (integers)
Category filter	`categories` (names)	`category_ids` — HG category IDs (strings)
Result cap	`maxProducts` (1–50)	`max_results` (1–50)

Stop sending products, vendors, or categories (names) — they are no longer accepted. Resolve names to IDs first via product_search_and_enrich (product IDs), get_vendor_information (vendor IDs), list_product_categories (category IDs).

An additive warning field is included in the response when filters were provided but no products matched.

Parameters​

Response Format​

Field meanings​

Credits​

Example Usage​

Related Tools​

Changelog​

2026-08-04 — Unified API PR #326 alignment​

2026-07-31 — Breaking: params renamed to snake_case​

2026-07-30 — Breaking: identifier and filter inputs changed (ID-based)​

Breaking change​