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

# Search companies

> Find visible companies by name, key, or LinkedIn URL fragment.

Search companies that have at least one visible person in the authenticated organization's graph. Matching is case-insensitive and checks the company name, FreshTalent company key, and LinkedIn URL. Results are ordered by the number of visible people and capped at 50; this endpoint has no pagination parameters.

## Query

<ParamField query="q" type="string">
  Optional company-name, key, or LinkedIn URL fragment. The Gateway trims the value. Omit it, or send an empty value, to browse all companies with visible people.
</ParamField>

The search response uses the `CompanySummary` shape. For this endpoint, `current_count` is the number of distinct visible people linked to the company, while `alum_count` is `0` and `role_mix` is `{}`. Use [Get company orbit](/api-reference/companies/orbit) for the calculated current/alumni counts, role mix, and people lists.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --fail-with-body --max-time 30 --get "https://api.freshtalent.ai/v1/companies" \
    --data-urlencode "q=anduril" \
    -H "Authorization: Bearer $FRESHTALENT_API_KEY"
  ```

  ```javascript JavaScript (fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({ q: "anduril" });
  const response = await fetch(`https://api.freshtalent.ai/v1/companies?${params}`, {
    signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  const body = await response.json();
  for (const company of body.data) console.log(company.key, company.current_count);
  ```

  ```python Python (stdlib) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import json
  import os
  from urllib.parse import urlencode
  from urllib.request import Request, urlopen

  url = "https://api.freshtalent.ai/v1/companies?" + urlencode({"q": "anduril"})
  request = Request(
      url,
      headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
  )
  with urlopen(request, timeout=30) as response:
      body = json.load(response)
  for company in body["data"]:
      print(company["key"], company["current_count"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "data": [
      {
        "key": "anduril",
        "name": "Anduril Industries",
        "linkedin_url": "https://www.linkedin.com/company/anduril-industries",
        "current_count": 42,
        "alum_count": 0,
        "role_mix": {}
      }
    ]
  }
  ```
</ResponseExample>

## Response schema

| Field                                | Type           | Meaning                                                                                   |
| ------------------------------------ | -------------- | ----------------------------------------------------------------------------------------- |
| `data`                               | object\[]      | Up to 50 company summaries; no pagination metadata                                        |
| `data[].key`                         | string         | Company identifier for the orbit route                                                    |
| `data[].name`, `data[].linkedin_url` | string or null | Display name and LinkedIn URL                                                             |
| `data[].current_count`               | integer        | Distinct visible people with a recorded position here, not just currently employed people |
| `data[].alum_count`                  | integer        | Always 0 on search; not an actual alumni count                                            |
| `data[].role_mix`                    | object         | Always empty on search; use the orbit for role counts                                     |

## Errors and recovery

* `401 unauthorized`: provide a valid API key in `Authorization: Bearer ...`.
* `402 payment_required`: restore active organization access.
* `5xx` or a transient network failure: retry this read with bounded backoff, jitter, and a timeout.
* `429`: retry this idempotent `GET` with exponential backoff and jitter after slowing down. The shared Gateway limit is 300 requests per minute per client IP as the Gateway sees it. Honor `Retry-After`; see [Rate limits](/rate-limits).

An empty `data` array is a successful search with no visible company match, not a `404`. See [Errors](/errors) for the common error envelope.

## Next steps

Use the returned `key` with [Get company orbit](/api-reference/companies/orbit) to retrieve the current team, leavers, role mix, and company metadata.