company_spend next channel

Status: Modified (batch selectors; v2 dedicated spend endpoint; 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-spend.md.

Retrieve IT spend data for companies from HG Insights v2. Accepts a batch of up to 25 companies and returns one entry per matched company under companies[]. The 25-company cap is the HG spend batch limit.

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

Parameters

Parameter	Type	Required	Default	Description
hg_ids	string[]	Optional	—	HG Insights company IDs for batch spend lookup (up to 25). Provide hg_ids or domains (at least one is required); both may be combined.
domains	string[]	Optional	—	Company domains for batch spend lookup (e.g. ['cisco.com', 'salesforce.com'], up to 25). Protocol prefixes, leading www., and trailing paths are stripped automatically.
category_ids	string[]	Optional	—	Filter spend records by HG category IDs. Forwarded as filters.spend.categories.ids to the upstream.
category_names	string[]	Optional	—	Filter spend records by category names. Forwarded as filters.spend.categories.names to the upstream.
max_results	integer	Optional	—	Maximum number of spend rows to return (1–25 — the HG spend pagination cap).
offset	integer	Optional	—	Zero-based row offset for pagination.

Response Format

{
  "companies": [
    {
      "company_id": "3AB6196C…",
      "company_domain": "cisco.com",
      "spend": {
        "all": [
          { "category_name": "Security", "country_name": "United States", "spend": 500000 }
        ],
        "all_count": 1
      },
      "credits_consumed": 3
    }
  ]
}

Response notes

• Unmatched companies are omitted from the array.
• Empty result (company has no spend data) returns { spend: { all: [], all_count: 0 } } — no throw.
• spend.all rows are snake_case upstream passthrough — the exact field set is governed by the v2 API contract.
• credits_consumed is 3 per company.

Example Usage

{
  "tool": "company_spend",
  "parameters": {
    "domains": ["cisco.com", "salesforce.com"],
    "category_names": ["Security"]
  }
}

Related Tools

• company_enrich — multi-section enrichment including spend in a single call.
• company_cloud_spend — cloud vendor and technology service data (separate from IT spend by category).

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.

Why this changed: aligns company_spend with the additive batch capability and dedicated spend endpoint shipped in unified API PR #326.

Breaking change — company selection is now batch-only

• The singular hg_id / company_domain selectors are removed. Select companies with batch arrays: hg_ids (array, ≤25) and/or domains (array, ≤25). At least one is required.
• The output is now a { companies: [...] } array.
• Migration: hg_id: "abc" → hg_ids: ["abc"], company_domain: "cisco.com" → domains: ["cisco.com"], then read response.companies[].

Breaking change — endpoint change

The tool now calls POST /data-api/v2/companies/enrich with fields: ['spend']. Pagination is nested under pagination.spend.{ limit, offset }.

The Redis cache schema version was bumped so pre-#326 cached payloads are not served.

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
Category filter	categoryIds / categoryNames	category_ids / category_names
Pagination	maxResults	max_results

Output before: { "companyId": "abc123", "companyDomain": "cisco.com", "spend": { … }, "creditsConsumed": 3 }

Output after: { "company_id": "abc123", "company_domain": "cisco.com", "spend": { … }, "credits_consumed": 3 }

2026-07-30 — Breaking: v2 migration; thin passthrough output; integration key changed

Why this changed: company_spend replaces four separate v1 API calls (domain match → category catalog → spend data → country catalog) with a single call to the unified POST /v2/companies/enrich endpoint.

Breaking changes

	Before	After
Integration key	hginsights (v1)	hginsights_v2__data_api
hg_id	snake_case optional	Removed — replaced by hgId (subsequently renamed to hg_id)
spendCategory	fuzzy string filter via Fuse.js	Removed — replaced by categoryIds / categoryNames
limit	1–200	Removed — replaced by maxResults (1–25)
fields / full	array / boolean	Removed

Output changed from a nested hierarchical shape (totalSpend, spendByCategory[].spendByCountry[]) to a thin v2 passthrough { spend: { all, all_count }, creditsConsumed }.

What stayed the same: tool key company_spend, credit cost (3 per call), companyDomain parameter, domain normalization, and the empty-result behavior ({ spend: { all: [], all_count: 0 } }).