Companies - Usage Metrics

Benchmark technology usage within a cohort for a given company.
Returns normalized metrics per product (1%–100%), so you can rank adoption and identify gaps.

Base URL: https://api.salescaddy.ai/api

---

Endpoint

GET /companies/{companyDomain}/cohort/{cohort}/metrics/usage

Path parameters

Name	Type	Required	Description
companyDomain	string	Yes	Subject company domain (e.g. microsoft.com)
cohort	CohortTypeEnum	Yes	Default | Defined | Aspirational

Query parameters

Name	Type	Required	Description
vendorDomain	string	No	Filter results to a single vendor (e.g., microsoft.com)
productId	string	No	Filter results to a single product ID (e.g., 16e299ae-0256-44e3-8989-7647815550d4)

The response is a JSON array of UsageMetricDTO (not paginated). Use filters to reduce payload size.

UsageMetricDTO (trimmed, conceptual)

JSON

[
	{
    "percentage": 18,
    "product": "salesforce sales cloud",
    "category": "CRM"
  }
]

---

Example — Filter by vendorDomain

Bash

curl -sS "https://api.salescaddy.ai/api/companies/microsoft.com/cohort/Default/metrics/usage?vendorDomain=salesforce.com" \
  -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

import os, requests
r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 params={"vendorDomain":"microsoft.com"},
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

using System.Net.Http.Headers;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", TOKEN);
var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?vendorDomain=microsoft.com");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

[
  {
    "percentage": 30,
    "product": "salesforce crm",
    "category": "Analytics Platforms"
  },
  {
    "percentage": 29,
    "product": "tableau",
    "category": "Analytics Platforms"
  },
  {
    "percentage": 10,
    "product": "salesforce crm analytics",
    "category": "Analytics Platforms"
  },
  {
    "percentage": 6,
    "product": "salesforce crm analytics (formerly tableau crm)",
    "category": "Analytics Platforms"
  },
]

---

Example — Filter by productId

Bash

curl -sS "https://api.salescaddy.ai/api/companies/microsoft.com/cohort/Default/metrics/usage?productId=16e299ae-0256-44e3-8989-7647815550d4" \
  -H "Authorization: Bearer $TOKEN"

Node

const url = "https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?productId=prod_office365";
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TOKEN}` } });
console.log(await res.json());

Python

r = requests.get("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage",
                 params={"productId":"prod_office365"},
                 headers={"Authorization": f"Bearer {os.environ['TOKEN']}"})
print(r.json())

C#

var res = await http.GetAsync("https://api.salescaddy.ai/api/companies/hilton.com/cohort/Default/metrics/usage?productId=prod_office365");
Console.WriteLine(await res.Content.ReadAsStringAsync());

Sample response (trimmed):

JSON

[
  {
    "percentage": 18,
    "product": "salesforce sales cloud",
    "category": "CRM"
  }
]

---

Notes & best practices

• Metrics are normalized (1 –100%) — perfect for ranking & visualizations.
• Results are not paginated; use vendorDomain/productId to reduce size if needed.
• Sorting is not guaranteed — sort on the client (e.g., by adoption or intensity).
• For deterministic validation, pair with:
  • POST /companies/{domain}/products-in-use — confirm presence of specific products.
  • GET /companies/{domain}/products/paged — fetch installed products with details.

---

Errors

Code	Meaning	How to fix
400	Bad request	Validate cohort enum and filter types.
401	Unauthorized	Provide/refresh Bearer token.
403	Forbidden	Check client permissions.
404	Not found	Unknown companyDomain or cohort not configured.
429	Rate limit exceeded	Retry with exponential backoff; respect Retry-After.
500	Internal server error	Retry later; contact support if persistent.

---