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

# Headcount Trends API

> Fetches a company's LinkedIn-sourced headcount data, including total employee count, historical growth trends, and a functional breakdown of the workforce.

## Overview

The Headcount Trends API returns a company's employee headcount signals sourced from LinkedIn, including the current total employee count, month-over-month headcount history, growth rates over multiple lookback periods, and a breakdown of headcount by function (e.g. Engineering, Sales, Marketing). Results are returned in the API response.

## Endpoint Details

* **Method:** GET
* **Endpoint:** `/v1/company/headcount-trends`

## Authentication requirements

* Include a valid API key in the `x-api-key` request header.

## Request

### Request Parameters

#### Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key.
</ParamField>

## URL Parameters

<ParamField query="company" type="string" required>
  Company website (e.g. `canva.com`) or a company UUID (e.g. `00000l1`). The UUID can be obtained from the Company Search API.
</ParamField>

#### Example Request

```bash theme={null}
curl -G "https://api.akta.pro/api/v1/company/headcount-trends/" \
  --data-urlencode "company=00000l1" \
  -H "x-api-key: YOUR_API_KEY"
```

## Response

#### Successful Response Fields

Returns a JSON object with the following structure:

<ResponseField name="data" type="object">
  Container object holding the company's headcount data. See **Headcount Object Fields** below.
</ResponseField>

<ResponseField name="credits_consumed" type="float">
  Credits consumed by the request.
</ResponseField>

#### Headcount Object Fields

<ResponseField name="uuid" type="string">
  Akta UUID of the company.
</ResponseField>

<ResponseField name="linkedin_username" type="string">
  LinkedIn numeric username/identifier for the company page.
</ResponseField>

<ResponseField name="linkedin_official_name" type="string">
  Company name as listed on LinkedIn.
</ResponseField>

<ResponseField name="linkedin_id" type="string">
  LinkedIn company ID.
</ResponseField>

<ResponseField name="total_employees" type="integer">
  Current total employee count as of `date`.
</ResponseField>

<ResponseField name="date" type="string">
  Date the headcount snapshot was taken, formatted as `YYYY-MM-DD`.
</ResponseField>

<ResponseField name="growth_periods" type="array of objects">
  Headcount growth rate over several trailing lookback windows. See **Growth Period Object** below.
</ResponseField>

<ResponseField name="headcount_growth" type="array of objects">
  Month-by-month historical headcount series. See **Headcount Growth Object** below.
</ResponseField>

<ResponseField name="headcount_by_function" type="array of objects">
  Current headcount broken down by job function. See **Headcount By Function Object** below.
</ResponseField>

#### Growth Period Object

<ResponseField name="month_difference" type="integer">
  Length of the trailing lookback window, in months (e.g. `6`, `12`, `24`).
</ResponseField>

<ResponseField name="change_percentage" type="integer">
  Percentage change in total headcount over the lookback window.
</ResponseField>

#### Headcount Growth Object

<ResponseField name="employee_count" type="integer">
  Total employee count as of `date`.
</ResponseField>

<ResponseField name="date" type="string">
  Snapshot date for this data point, formatted as `YYYY-MM-DD`.
</ResponseField>

#### Headcount By Function Object

<ResponseField name="name" type="string">
  Job function name (e.g. `Engineering`, `Sales`, `Arts and Design`).
</ResponseField>

<ResponseField name="employee_count" type="integer">
  Current employee count in this function.
</ResponseField>

<ResponseField name="growth_periods" type="array of objects">
  Growth rate for this function over trailing lookback windows. Same shape as the top-level **Growth Period Object**, typically returned for `6` and `12` month windows.
</ResponseField>

<ResponseExample>
  ```json 200 expandable wrap theme={null}
  {
    "data": {
      "uuid": "00000l1",
      "linkedin_username": "2850862",
      "linkedin_official_name": "Canva",
      "linkedin_id": "2850862",
      "total_employees": 17694,
      "growth_periods": [
        {
          "month_difference": 6,
          "change_percentage": 29
        },
        {
          "month_difference": 12,
          "change_percentage": 73
        },
        {
          "month_difference": 24,
          "change_percentage": 111
        }
      ],
      "headcount_growth": [
        {
          "employee_count": 8376,
          "date": "2024-07-01"
        },
        {
          "employee_count": 9076,
          "date": "2025-01-01"
        },
        {
          "employee_count": 10202,
          "date": "2025-07-01"
        },
        {
          "employee_count": 13716,
          "date": "2026-01-01"
        },
        {
          "employee_count": 17694,
          "date": "2026-07-01"
        }
      ],
      "date": "2026-07-01",
      "headcount_by_function": [
        {
          "name": "Arts and Design",
          "employee_count": 5113,
          "growth_periods": [
            {
              "month_difference": 6,
              "change_percentage": 42
            },
            {
              "month_difference": 12,
              "change_percentage": 78
            }
          ]
        },
        {
          "name": "Engineering",
          "employee_count": 2544,
          "growth_periods": [
            {
              "month_difference": 6,
              "change_percentage": 18
            },
            {
              "month_difference": 12,
              "change_percentage": 35
            }
          ]
        },
        {
          "name": "Sales",
          "employee_count": 769,
          "growth_periods": [
            {
              "month_difference": 6,
              "change_percentage": 51
            },
            {
              "month_difference": 12,
              "change_percentage": 124
            }
          ]
        }
      ]
    },
    "credits_consumed": 2.5
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/company/headcount-trends
openapi: 3.0.3
info:
  title: Akta.pro API
  description: >
    Akta provides APIs for company intelligence and news monitoring:


    1. **News** – Enriched news articles with AI summaries, sentiment, event
    tags, industry classifications, and company mention resolution.

    2. **Company Enrichment** – Structured company data including firmographics,
    funding, headcount, and financials.

    3. **Company Search** – Free endpoint to resolve company names, domains, or
    UUIDs.

    4. **Product Reviews** – G2 product reviews with ratings and review content.

    5. **Employee Reviews** – Employee sentiment data with workplace ratings.


    **Authentication:** All endpoints require an API key in the `x-api-key` HTTP
    header.
  version: 1.0.0
  contact:
    url: https://akta.pro
servers:
  - url: https://api.akta.pro/api
    description: Production server
security: []
tags:
  - name: News
    description: Enriched news articles with AI summaries, sentiment, and company mentions
  - name: Company
    description: Company data enrichment and search
  - name: Reviews
    description: Product and employee reviews from external sources
externalDocs:
  description: Official Akta.pro API Documentation
  url: https://docs.akta.pro
paths:
  /v1/company/headcount-trends:
    get:
      tags:
        - Company
      summary: Headcount Trends
      description: >
        Fetches a company's LinkedIn-sourced headcount data, including total
        employee count, historical growth trends, and a functional breakdown of
        the workforce.
      operationId: getHeadcountTrends
      parameters:
        - name: company
          in: query
          required: true
          schema:
            type: string
          description: >-
            Company website (e.g. 'canva.com') or a company UUID. The UUID can
            be obtained from the Company Search API.
      responses:
        '200':
          description: Headcount trends data returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      uuid:
                        type: string
                      linkedin_username:
                        type: string
                      linkedin_official_name:
                        type: string
                      total_employees:
                        type: integer
                      date:
                        type: string
                      growth_periods:
                        type: array
                      headcount_growth:
                        type: array
                      headcount_by_function:
                        type: array
                  credits_consumed:
                    type: number
                    format: float
        '401':
          description: Unauthorized — missing or invalid API key.
      security:
        - xApiKeyAuth: []
components:
  securitySchemes:
    xApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from your Akta account.

````