---
title: "Company timelines (bulk)"
method: POST
path: "/v1/companies/timeline"
tags: ["companies"]
---

# Company timelines (bulk)

`POST /v1/companies/timeline`

## Request

- Base URL: `https://api.datahyena.com`
- URL: `https://api.datahyena.com/v1/companies/timeline`
- Auth: API key in header `X-API-Key`

Resolve up to 25 companies and return each timeline. Costs one credit per record (company plus each included event) per resolved company. Companies are served in order until credits run out; the rest are marked skipped. Unresolved companies cost nothing.

## Request body

- CompanyTimelineBulkDto
  - `companies` CompanyTimelineSelectorDto[], required: Companies to resolve, each by id, domain, name, or linkedinUrl. 1 to 25 per request.
    - `id` string: Datahyena company id.
    - `domain` string
    - `name` string
    - `linkedinUrl` string
  - `include` string[]: Which event kinds to include. Defaults to all. Each pulled event costs one credit.

## Response `200`

- CompanyTimelineBulkItemDto[]
  - `query` object, required: The selector this entry was resolved from.
  - `status` 'served' | 'skipped_insufficient_credits' | 'not_found', required
  - `cost` number: Credits this timeline costs (company + events). Present when resolved.
  - `timeline` CompanyTimelineDto
    - `company` PublicCompanyDto, required
      - `id` object, nullable, required
      - `name` string, required
      - `domain` object, nullable, required
      - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
      - `description` object, nullable, required
      - `linkedinHandle` object, nullable, required
      - `linkedinUrl` object, nullable, required
      - `linkedinGeoId` object, nullable, required
      - `linkedinIndustryId` object, nullable, required
      - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
      - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
      - `hqCity` object, nullable, required
      - `hqCountry` CountryDto, required
        - `code` string, required: ISO 3166-1 alpha-2 country code.
        - `name` string, required: Human-readable country name.
      - `industryGroup` object, nullable, required
      - `industrySubTags` string[], required
      - `verticals` string[], required
      - `employeeCountBucket` object, nullable, required
      - `foundedYear` object, nullable, required
      - `businessModel` object, nullable, required
    - `investors` CompanyTimelineInvestorDto[], required
      - `id` string, nullable, required
      - `name` string, required
    - `events` CompanyTimelineEventDto[], required: Funding rounds, acquisitions, executive moves and hiring signals, most recent first.
      - `kind` 'funding' | 'acquisition' | 'exec_move' | 'hiring', required
      - `date` string, nullable, required: Announcement date (ISO 8601).
      - `funding` PublicFundingEventResponseItem
        - `id` string, required
        - `round` object, nullable, required
        - `roundStated` object, nullable, required: True when the source stated this round stage explicitly; false when it was inferred; null when no round is recorded.
        - `amountUsdCents` object, nullable, required
        - `amountUsd` object, nullable, required
        - `amountOriginalCurrency` object, nullable, required
        - `amountOriginalCents` object, nullable, required
        - `investors` FundingEventInvestorDto[], required
          - `id` string, required
          - `name` string, required
        - `announcedAt` object, nullable, required
        - `discoveredAt` string, required
        - `company` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required
      - `acquisition` PublicAcquisitionEventResponseItem
        - `id` string, required
        - `dealAmountUsdCents` object, nullable, required
        - `dealAmountUsd` object, nullable, required
        - `dealAmountOriginalCurrency` object, nullable, required
        - `dealAmountOriginalCents` object, nullable, required
        - `paymentType` 'cash' | 'stock' | 'mixed' | 'undisclosed', nullable, required
        - `isMerger` boolean, required
        - `announcedAt` object, nullable, required
        - `closingAt` object, nullable, required
        - `discoveredAt` string, required
        - `acquirer` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required
        - `target` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required
      - `execMove` PublicExecMoveEventResponseItem
        - `id` string, required
        - `person` ExecMovePersonDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
        - `role` string, required
        - `roleSeniority` 'c_level' | 'vp_level' | 'founder', required
        - `moveType` 'appointment' | 'promotion' | 'departure' | 'transition', required
        - `announcedAt` object, nullable, required
        - `effectiveDate` object, nullable, required
        - `discoveredAt` string, required
        - `company` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required
        - `fromCompany` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required
      - `hiring` PublicHiringSignalResponseItem
        - `id` string, required
        - `eventType` string, required
        - `function` string, required: The function the signal is about, or all for company-wide signals.
        - `seniority` object, nullable, required
        - `roleFamily` object, nullable, required: The role family the signal is about, for example sales_development or revops.
        - `country` CountryDto, required
          - `code` string, required: ISO 3166-1 alpha-2 country code.
          - `name` string, required: Human-readable country name.
        - `technologies` string[], required: Technologies named across the roles behind the signal.
        - `announcedAt` string, required: When the signal started.
        - `endedAt` object, nullable, required: When every role behind it closed.
        - `active` boolean, required: Whether any role behind the signal is still open.
        - `roleCount` number, required: Number of open roles behind the signal.
        - `roles` HiringRoleDto[], required: Up to 10 roles behind the signal.
          - `title` string, required
          - `function` string, required
          - `seniority` string, required
          - `roleFamily` object, nullable, required
          - `location` object, nullable, required
          - `postedAt` object, nullable, required
          - `url` object, nullable, required
          - `salary` HiringSalaryDto, required
            - `min` object, nullable, required
            - `max` object, nullable, required
            - `currency` object, nullable, required
            - `interval` 'year' | 'month' | 'week' | 'day' | 'hour', nullable, required
          - `technologies` string[], required: Technologies the role names.
        - `board` string, required: The company's hiring platform.
        - `discoveredAt` string, required
        - `company` PublicCompanyDto, required
          - `id` object, nullable, required
          - `name` string, required
          - `domain` object, nullable, required
          - `website` object, nullable, required: The address the company website loads at, which can differ from domain (for example a www host). Null when no working site is known.
          - `description` object, nullable, required
          - `linkedinHandle` object, nullable, required
          - `linkedinUrl` object, nullable, required
          - `linkedinGeoId` object, nullable, required
          - `linkedinIndustryId` object, nullable, required
          - `naicsCode` object, nullable, required: NAICS 2022 code derived from the industry classification. Null when no honest mapping exists.
          - `naicsLevel` 2 | 3 | 4, nullable, required: Depth of naicsCode: 2 = sector, 3 = subsector, 4 = industry group.
          - `hqCity` object, nullable, required
          - `hqCountry` CountryDto, required
            - `code` string, required: ISO 3166-1 alpha-2 country code.
            - `name` string, required: Human-readable country name.
          - `industryGroup` object, nullable, required
          - `industrySubTags` string[], required
          - `verticals` string[], required
          - `employeeCountBucket` object, nullable, required
          - `foundedYear` object, nullable, required
          - `businessModel` object, nullable, required

## Other responses

- `400`: Invalid query parameter, body, or pagination cursor.
- `401`: Missing, invalid, or disabled API key.
- `402`: Workspace has no credits available for the request.
- `403`: Request blocked by abuse prevention policy.
- `429`: Rate limit exceeded for this workspace and plan.

---

[API](https://skmtc.dev/datahyena/apis/datahyena-public-api.md) · [All operations](https://skmtc.dev/datahyena/apis/datahyena-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/datahyena/apis/datahyena-public-api/revisions/0de0060625e4?raw)