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

# Look up known companies

> Inspect current evidence for up to twenty company IDs or domains.

`get_companies` is an authenticated Jolts MCP tool. [Connect your assistant](/mcp-overview) first.

Retrieve existing company evidence for one to twenty known targets. Supply **either** `ids`
(positive integers) **or** `domains` (hostnames), never both. A single target uses a one-element
array. This operation does not call providers or AI, discover missing companies, or refresh data.

## Arguments

| Argument      | Type          | Requirement                                                   |
| ------------- | ------------- | ------------------------------------------------------------- |
| `ids`         | Integer array | 1–20 positive company IDs; omit when using domains            |
| `domains`     | String array  | 1–20 hostnames; omit when using IDs                           |
| `request_key` | String        | Required unless supplied through the `Idempotency-Key` header |

Supply exactly one target array. Unknown arguments are rejected. Use hostnames, not full URLs or
email addresses. See [known-account research](/use-cases/research-target-accounts) for a workflow.

## Example call

This is the `params` object of a JSON-RPC `tools/call`, not a complete HTTP request.

```json theme={null}
{
  "name": "get_companies",
  "arguments": {
    "domains": ["northstar.example.test", "missing.example.test"],
    "request_key": "company-lookup-1"
  }
}
```

These hostnames are fictional. The response always contains a `companies` list and a `lookups`
list accounting for every normalized, distinct target. Outcomes are `found`, `not_found`, or
`ambiguous`; an identical retry can report `unavailable` when previously delivered support is
no longer eligible. A miss means absent from our permitted dataset, not that the company does not
exist. Shared domains never silently select an arbitrary company.

Each returned company has identity, supported domains and up to three recent observations.
This is not a complete organization profile. Source references and observation dates accompany
the evidence. A completed lookup consumes one request unit and one delivered unit per distinct
company. Missing or ambiguous targets consume no company units. There are no overage charges.

Provide `request_key` or the `Idempotency-Key` header. Identical retries reuse the settled
operation; changing targets requires a new key. Current subscription and capacity limits apply.

## Read the response

Read `result.structuredContent`; text-only clients receive the same JSON in `result.content`.
Check `result.isError` before using data. A successful HTTP status alone does not prove tool success.
See [response examples](/mcp-responses) and [error handling](/troubleshooting).

| Lookup outcome | Meaning                                       | Next step                                              |
| -------------- | --------------------------------------------- | ------------------------------------------------------ |
| `found`        | A company has eligible evidence               | Read its observations and sources                      |
| `not_found`    | No eligible match in the dataset              | Do not claim the company does not exist                |
| `ambiguous`    | The target cannot identify one company safely | Resolve identity before using the result               |
| `unavailable`  | Replayed evidence is no longer deliverable    | Respect the withdrawal; do not restore cached evidence |

For the complete result fields, see the [HTTP lookup response](/api-reference/companies/get-companies).
If the operation is pending, retain `usage.id` and call [get\_usage](/tools/get-usage) instead of
submitting another lookup under a new key.

## Related

* [Choose a tool](/mcp-tools)
* [Company-list workflows](/workflows)
* [Understand evidence](/evidence)