# Estimate credit cost for Company Hierarchy

Returns the estimated credit cost for a Company Hierarchy request without consuming any
credits or returning data. Use the same parameters as the `/hierarchy` endpoint.

Endpoint: POST /data-api/v2/companies/hierarchy/estimate
Security: authorization

## Security:

  - `authorization` (unknown)
    http bearer API_KEY

## Request body:

  - `application/json` (unknown)
    Hierarchy estimate request

## Request fields (application/json):

  - `filters` (object)
    Optional filters applied to the hierarchy results. `countries`, `regions`, and `tiers` require `format: list` and are rejected with HTTP 400 (`FILTER_NOT_VALID_FOR_TREE`) when used with `format: tree`. `max_tier` works with both `tree` and `list`.
    Example: {"countries":["BR"],"regions":["EMEA"]}

  - `filters.countries` (array)
    Restrict results to companies in these ISO-3166-1 alpha-2 country codes. Requires `format: list` (not supported with `format: tree`).

  - `filters.max_tier` (string)
    Restrict results to companies at or above this hierarchy tier. Works with both `tree` and `list` formats; use it to limit tree depth.
    Enum: "group_hq", "corporate_parent", "domestic_parent", "subsidiary"

  - `filters.regions` (array)
    Restrict results to companies in these geopolitical regions. Combined with `countries` using union (OR) semantics. Requires `format: list` (not supported with `format: tree`).

  - `filters.tiers` (array)
    Restrict results to companies at these hierarchy tiers. Requires `format: list` (not supported with `format: tree`).

  - `format` (string)
    Controls the response shape: `tree` (nested) or `list` (flat). Defaults to `tree`.
The `countries`, `regions`, and `tiers` filters require `format: list`; sending any of them
with `format: tree` (including the default when `format` is omitted) returns HTTP 400
(`FILTER_NOT_VALID_FOR_TREE`). The `max_tier` filter works with both formats and can be used
to limit tree depth.
    Enum: "tree", "list"

  - `hierarchy` (object, required)
    Identifies a company by ID or domain (mutually exclusive).

  - `hierarchy.domain` (string)
    Company domain (e.g., example.com)

  - `hierarchy.id` (string)
    Hexadecimal identifier (unsigned 128-bit base 16 integer)
    Example: 1698C53EBC888758570396E0334965C1

  - `mode` (string, required)
    Controls which part of the corporate hierarchy to return.
- `full` — returns the entire tree rooted at the Group HQ, regardless of which company was matched. Every node in the corporate family is included.
- `children` — returns a subtree rooted at the matched company, including all of its subsidiaries and their descendants.
- `parents` — returns only the ancestor chain from the Group HQ down to the matched company (no siblings or cousins).
    Enum: "full", "children", "parents"

  - `selected_fields` (array)
    Optional field override. When provided, only these fields (plus always-present selected) are returned.

  - `sort` (array)
    Optional list of sort directives applied to the hierarchy results.

  - `sort.field` (string, required)
    Field to sort by.
    Enum: "revenue_total", "employees_total", "name"

  - `sort.nulls` (string)
    Where to place null values.
    Enum: "first", "last"

  - `sort.order` (string)
    Sort order.
    Enum: "asc", "desc"

## Response 200:

  - `200` (unknown)
    Estimate response

## Response 200 fields (application/json):

  - `available_credits` (integer, required)
    Credits available in the org's active consumption cycle.

  - `credits_estimate` (number, required)
    Estimated number of credits required to fulfill the hierarchy request.

  - `sufficient_credits` (boolean, required)
    Whether the org has enough credits to cover the estimate.

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: The api key provided is not valid

  - `errors.source` (string)

  - `errors.title` (string, required)
    Example: Unauthorized

## Response 422:

  - `422` (unknown)
    Unprocessable Entity

## Response 422 fields (application/json):

  - `errors` (array, required)

  - `errors.detail` (string, required)
    Example: null value where string expected

  - `errors.source` (object, required)

  - `errors.source.pointer` (string, required)
    Example: /data/attributes/petName

  - `errors.title` (string, required)
    Example: Invalid value

## Response 503:

  - `503` (unknown)
    Service Unavailable

## Response 503 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: Unable to verify credit availability. Please try again later. If the error persists, contact customersupport@hginsights.com.

  - `errors.source` (string)

  - `errors.title` (string, required)
    Example: Service unavailable