List employee counts

Return historical year-end employee counts. By default the collection walks every company in symbol order, newest fiscal year first within each company; pass identifier to restrict it to one company. Counts are company-level data, so secondary listings resolve to the primary company record.

GET/v3.0.0/company/employees

Plan Access

Free

(Your plan)

Individual

$29/mo

Professional

$89/mo

Plan History

Free

(Your plan)

2 years

Individual

$29/mo

5 years

Professional

$89/mo

All available

Parameters

Query parameters

identifierstringoptional

Restrict results to a single company. Accepts a company-profile ID (cmp_…), a ticker ID (tkr_…), an exchange and symbol separated by a colon (e.g. NASDAQ:AAPL), or a FIGI. Secondary listings resolve to the primary company record. Omit to walk employee counts across all companies.

Example: NASDAQ:AAPL
fiscal_yearintegeroptional

Pass a four-digit fiscal year directly for an exact match. For a range, combine the modifiers below, for example, fiscal_year.gte=2020&fiscal_year.lte=2025.

Example: 2025
+ Show filter modifiers
fiscal_year.gteinteger

Return counts whose fiscal year is greater than or equal to the given year.

fiscal_year.gtinteger

Return counts whose fiscal year is strictly greater than the given year.

fiscal_year.lteinteger

Return counts whose fiscal year is less than or equal to the given year.

fiscal_year.ltinteger

Return counts whose fiscal year is strictly less than the given year.

orderstringoptional

Sort fiscal years within each company (fiscal_year). Companies always sort by symbol in ascending order.

Default: descValues: ascdesc
limitintegeroptional

Maximum number of resources to return.

Default: 100Min: 1Max: 500
pagestringoptional

Opaque page token from a previous response. Follow the returned page URL when possible.

Response

Each item is a v3.reference.employee_count reporting one company's employee figure for one fiscal year. Fiscal years without a reported figure are omitted, so the series can have gaps. Within each company, results sort by fiscal year in descending order by default; pass order=asc for oldest first.

Response fields

dataarray of objects

Array of employee-count resources for the current page.

+ Show child attributes
idstring

Unique identifier for the employee-count record, beginning with emp_. It is derived deterministically from the primary listing and fiscal year, so the same record always keeps the same ID.

objectstring

String representing the object's type, always v3.reference.employee_count for this resource.

symbolstring

Qualified symbol of the company's primary listing, combining the exchange code and ticker separated by a colon, e.g. NASDAQ:AAPL. Employee counts are company-level data, so secondary listings resolve to the primary listing.

fiscal_yearnumber

Fiscal year the count reports on, e.g. 2025. Counts are year-end values from the company's annual report, so the calendar date depends on the company's fiscal calendar.

employeesnumber

Number of employees the company reported for that fiscal year. Some companies disclose average full-time equivalents instead of a headcount, so fractional values occur. Years without a reported figure are omitted from the collection.

next_page_urlnullable

URL of the next page of results, or null when there are no more pages. Request it unchanged to continue paging.

previous_page_urlnullable

URL of the previous page of results, or null on the first page.

Examples

Combine the filters below to answer common questions. Each request is runnable.

The full headcount history for one company:

curl "https://api.roic.ai/v3.0.0/company/employees?apikey=YOUR_API_KEY&identifier=NASDAQ:AAPL"

Walk every company's history page by page, following next_page_url:

curl "https://api.roic.ai/v3.0.0/company/employees?apikey=YOUR_API_KEY&limit=500"

One fiscal year across all companies:

curl "https://api.roic.ai/v3.0.0/company/employees?apikey=YOUR_API_KEY&fiscal_year=2025"

Growth over a decade, using a fiscal_year.gte=2015 lower bound with oldest years first:

curl "https://api.roic.ai/v3.0.0/company/employees?apikey=YOUR_API_KEY&identifier=NASDAQ:AAPL&fiscal_year.gte=2015&order=asc"

Reporting caveats

Companies report the figure in their annual filings, so it reflects each company's own definition: most disclose total headcount at fiscal year-end, while some disclose average full-time equivalents, which can be fractional. The latest year's value also appears as number_of_employees on the company profile.

Related endpoints

Request
curl "https://api.roic.ai/v3.0.0/company/employees?apikey=YOUR_API_KEY&identifier=NASDAQ:AAPL"
Response
200 OK
{
  "data": [
    {
      "id": "emp_GffJ20uF2eYdcVSGcUnjTx",
      "object": "v3.reference.employee_count",
      "symbol": "NASDAQ:AAPL",
      "fiscal_year": 2025,
      "employees": 166000
    },
    {
      "id": "emp_MAukBRt-HzGyPki6nLcPYf",
      "object": "v3.reference.employee_count",
      "symbol": "NASDAQ:AAPL",
      "fiscal_year": 2024,
      "employees": 164000
    },
    {
      "id": "emp_lnS56IM3VLm-ksZEdlTvNU",
      "object": "v3.reference.employee_count",
      "symbol": "NASDAQ:AAPL",
      "fiscal_year": 2023,
      "employees": 161000
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}