> ## Documentation Index
> Fetch the complete documentation index at: https://agent-docs.akta.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Headcount Trends API Use cases

> Growth snapshots, historical trend charting, function-level breakdown, and competitive benchmarking.

### Growth snapshot

Fetch the current headcount and growth rate across standard lookback windows for a company.

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.akta.pro/api/v1/company/headcount-trends/" \
    --data-urlencode "company=https://canva.com" \
    -H "x-api-key: your api key"
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.akta.pro/api/v1/company/headcount-trends"

  payload = {}
  headers = {
    'x-api-key': 'your api key'
  }
  params = {"company": "https://canva.com"}

  response = requests.request("GET", url, headers=headers, params=params, data=payload)

  print(response.text)
  ```
</CodeGroup>

**Sample response:**

```json expandable theme={null}
{
  "data": {
    "uuid": "00000l1",
    "linkedin_username": "canva",
    "linkedin_official_name": "Canva",
    "linkedin_id": "2850862",
    "total_employees": 18966,
    "growth_periods": [
      {
        "month_difference": 6,
        "change_percentage": 29
      },
      {
        "month_difference": 12,
        "change_percentage": 75
      },
      {
        "month_difference": 24,
        "change_percentage": 117
      }
    ],
    "headcount_monthly": [
      {
        "employee_count": 8746,
        "date": "2024-08-01"
      },
      {
        "employee_count": 8853,
        "date": "2024-09-01"
      },
      {
        "employee_count": 8933,
        "date": "2024-10-01"
      },
      {
        "employee_count": 8983,
        "date": "2024-11-01"
      },
      {
        "employee_count": 9040,
        "date": "2024-12-01"
      },
      {
        "employee_count": 9334,
        "date": "2025-01-01"
      },
      {
        "employee_count": 9463,
        "date": "2025-02-01"
      },
      {
        "employee_count": 9619,
        "date": "2025-03-01"
      },
      {
        "employee_count": 9788,
        "date": "2025-04-01"
      },
      {
        "employee_count": 10010,
        "date": "2025-05-01"
      },
      {
        "employee_count": 10245,
        "date": "2025-06-01"
      },
      {
        "employee_count": 10474,
        "date": "2025-07-01"
      },
      {
        "employee_count": 10837,
        "date": "2025-08-01"
      },
      {
        "employee_count": 11116,
        "date": "2025-09-01"
      },
      {
        "employee_count": 11708,
        "date": "2025-10-01"
      },
      {
        "employee_count": 12447,
        "date": "2025-11-01"
      },
      {
        "employee_count": 13066,
        "date": "2025-12-01"
      },
      {
        "employee_count": 13968,
        "date": "2026-01-01"
      },
      {
        "employee_count": 14653,
        "date": "2026-02-01"
      },
      {
        "employee_count": 15337,
        "date": "2026-03-01"
      },
      {
        "employee_count": 16032,
        "date": "2026-04-01"
      },
      {
        "employee_count": 16847,
        "date": "2026-05-01"
      },
      {
        "employee_count": 17798,
        "date": "2026-06-01"
      },
      {
        "employee_count": 18495,
        "date": "2026-07-01"
      },
      {
        "employee_count": 18966,
        "date": "2026-08-01"
      }
    ],
    "date": "2026-08-01",
    "headcount_by_function": [
      {
        "name": "Arts and Design",
        "employee_count": 5656,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 38
          },
          {
            "month_difference": 12,
            "change_percentage": 80
          }
        ]
      },
      {
        "name": "Engineering",
        "employee_count": 2541,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 13
          },
          {
            "month_difference": 12,
            "change_percentage": 34
          }
        ]
      },
      {
        "name": "Media and Communication",
        "employee_count": 1414,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 33
          },
          {
            "month_difference": 12,
            "change_percentage": 81
          }
        ]
      },
      {
        "name": "Marketing",
        "employee_count": 1107,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 34
          },
          {
            "month_difference": 12,
            "change_percentage": 66
          }
        ]
      },
      {
        "name": "Education",
        "employee_count": 1022,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 47
          },
          {
            "month_difference": 12,
            "change_percentage": 173
          }
        ]
      },
      {
        "name": "Sales",
        "employee_count": 821,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 41
          },
          {
            "month_difference": 12,
            "change_percentage": 115
          }
        ]
      },
      {
        "name": "Administrative",
        "employee_count": 644,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 42
          },
          {
            "month_difference": 12,
            "change_percentage": 132
          }
        ]
      },
      {
        "name": "Operations",
        "employee_count": 594,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 31
          },
          {
            "month_difference": 12,
            "change_percentage": 105
          }
        ]
      },
      {
        "name": "Information Technology",
        "employee_count": 588,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 7
          },
          {
            "month_difference": 12,
            "change_percentage": 27
          }
        ]
      },
      {
        "name": "Support",
        "employee_count": 403,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 21
          },
          {
            "month_difference": 12,
            "change_percentage": 54
          }
        ]
      },
      {
        "name": "Business Development",
        "employee_count": 416,
        "growth_periods": [
          {
            "month_difference": 6,
            "change_percentage": 25
          },
          {
            "month_difference": 12,
            "change_percentage": 108
          }
        ]
      }
    ]
  },
  "credits_consumed": 2.5
}
```

### Historical trend charting

Extract the `headcount_monthly` series to chart hiring trajectory over time, or flag inflection points such as sudden slowdowns or accelerations.

```python theme={null}
import requests

HEADERS = {"x-api-key": "your_api_key"}

response = requests.get(
    "https://api.akta.pro/api/v1/company/headcount-trends",
    headers=HEADERS,
    params={"company": "canva.com"}
)
response.raise_for_status()

series = response.json()["data"]["headcount_monthly"]

# Series is already chronological, but sort defensively
series = sorted(series, key=lambda p: p["date"])

print(f"{'Month':<12} {'Headcount':<12} {'MoM Change'}")
print("-" * 40)
prev = None
for point in series:
    count, date = point["employee_count"], point["date"]
    if prev is not None:
        change = (count - prev) / prev * 100
        change_str = f"{change:+.1f}%"
    else:
        change_str = "—"
    print(f"{date:<12} {count:<12,} {change_str}")
    prev = count
```

### Function-level breakdown

Identify which teams are driving overall headcount growth which could be useful for spotting a shift toward sales-led expansion, an engineering build-out, or disproportionate hiring in a single function.

```python theme={null}
import requests
import concurrent.futures

HEADERS = {"x-api-key": "your_api_key"}

WATCHLIST = ["canva.com", "figma.com"]

def fetch_headcount_functions(domain):
    try:
        r = requests.get(
            "https://api.akta.pro/api/v1/company/headcount-trends",
            headers=HEADERS,
            params={"company": domain}
        )
        r.raise_for_status()
        payload = r.json()

        data = payload.get("data", {})
        functions = data.get("headcount_by_function")

        if not functions:
            return domain, None, "No function-level headcount data available"

        return domain, functions, None

    except requests.exceptions.RequestException as e:
        return domain, None, f"Request failed: {e}"
    except ValueError:
        return domain, None, "Invalid JSON response"

def growth_12mo(fn):
    return next(
        (g["change_percentage"] for g in fn["growth_periods"] if g["month_difference"] == 12),
        0
    )

with concurrent.futures.ThreadPoolExecutor(max_workers=5) as pool:
    results = list(pool.map(fetch_headcount_functions, WATCHLIST))

for domain, functions, error in results:
    print(f"\n=== {domain} ===")
    if error:
        print(f"  Skipped: {error}")
        continue

    ranked = sorted(functions, key=growth_12mo, reverse=True)
    print(f"{'Function':<28} {'Headcount':<12} {'12mo Growth'}")
    print("-" * 55)
    for fn in ranked:
        print(f"{fn['name']:<28} {fn['employee_count']:<12,} {growth_12mo(fn)}%")
```

### Competitive benchmark across multiple companies

Fetch headcount and growth for a set of companies and compare hiring velocity side by side. This could be useful for tracking relative momentum within a competitive set.

```python theme={null}
import requests

HEADERS   = {"x-api-key": "<YOUR_API_KEY>"}
COMPANIES = ["canva.com", "figma.com", "notion.so", "miro.com"]

def get_growth(fn_list, months):
    return next(
        (g["change_percentage"] for g in fn_list if g["month_difference"] == months),
        None
    )

def get_headcount(company):
    r = requests.get(
        "https://api.akta.pro/api/v1/company/headcount-trends",
        headers=HEADERS,
        params={"company": company}
    )
    data = r.json()["data"]
    return {
        "company":  company,
        "total":    data["total_employees"],
        "growth_6mo":  get_growth(data["growth_periods"], 6),
        "growth_12mo": get_growth(data["growth_periods"], 12)
    }

results = [get_headcount(c) for c in COMPANIES]
results.sort(key=lambda x: x["growth_12mo"] or 0, reverse=True)

print(f"{'Company':<15} {'Employees':<12} {'6mo Growth':<12} {'12mo Growth'}")
print("-" * 55)
for r in results:
    print(f"{r['company']:<15} {r['total']:<12,} {r['growth_6mo']}%{'':<8} {r['growth_12mo']}%")
```