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

# Company Agent

A list-building agent that finds companies and the people at them, and returns them as structured rows. Building with a coding agent?
[Give your agent the full reference →](/documentation/integrating-tako/agent/for-coding-agent)

## Capabilities

The **Company Agent** builds lists of companies and the people at them. It starts from structured company and people data (company registries, licensed company and people profiles) and reads the web only to fill gaps. Use it for prospecting and research lists: "CISOs at American hospitals", "UK fintechs incorporated since 2020", "the executive officers at four airlines".

> **Lists as structured rows**
>
> Each list comes back as a card whose rows you can export through [Contents](/api-reference/contents): names, roles, companies, locations and LinkedIn URLs.

> **Contacts you pay for only when you want them**
>
> Work emails and phone numbers come back as locked columns. Review the list first, then reveal the contacts you want with a premium export.

> **Grounded and citable**
>
> The written `answer` carries `[n]` markers that join a top-level `citations` registry.

> **Asynchronous**
>
> Dispatch a run, then poll or stream it to completion. Most runs finish in about a minute.

For a written, synthesized answer, use the [Answer Agent](/documentation/integrating-tako/agent/answer). For schema-defined structured output over Tako's knowledge graph, use the [Retrieval Agent](/documentation/integrating-tako/agent/retrieval).

## Example

[Try in Playground](https://tako.com/console/playground/agent/company)

Dispatch a run, then poll `GET /v1/agent/company/runs/{run_id}` until `status` is `completed` or `failed`:

```bash theme={null}
# 1. Dispatch. Returns 202 with a CompanyAgentRun: {"run_id": "...", "status": "queued"}.
curl -X POST https://tako.com/api/v1/agent/company/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Show me the executive officers at Delta, United, American and Southwest."
  }'

# 2. Poll with the run_id until status is "completed" or "failed".
curl https://tako.com/api/v1/agent/company/runs/RUN_ID \
  -H "X-API-Key: YOUR_API_KEY"
```

## Effort

`effort` picks the tier. Omit it on a new thread and Tako uses `medium`.

* **`low`** answers from company registries and the web only. It screens companies by status, incorporation date, location and industry, and resolves named companies and people. It can't rank or filter by financial metrics such as revenue or headcount. Ask it for one and it answers the part it can and says which part it couldn't.
* **`medium`** (default) and **`high`** can use every source. `high` uses a stronger model and a larger budget, and always takes longer.

A thread keeps its effort. A follow-up that sends a different `effort` returns `409 effort_mismatch`, so start a new thread to change it.

## Get the rows and reveal contacts

Each list in `result.cards` is a card. Export its rows through [Contents](/api-reference/contents) with the card's `webpage_url`:

```bash theme={null}
curl -X POST https://tako.com/api/v1/contents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tako.com/card/CARD_ID/", "content_format": "csv" }'
```

Contact cells read `[premium: withheld]` in that export. To reveal them, send the same request with `"premium": true`. Each revealed contact bills at its premium rate, on top of the standard row rate, and the item's `premium_rows` reports the count. To reveal one slice of a long list, page it with `offset` and `max_rows`. Premium exports aren't available over MPP.

## Structured output

The Company Agent doesn't take an `output_schema` yet. A request that sends one returns `400`. Export a list's card through Contents to get its rows as data.

## Continue a thread

Each run belongs to a thread. Pass a prior run's `thread_id` to ask a follow-up in the same conversation, for example "Now add their heads of IT". Omit `thread_id` to start a fresh thread. A thread is pinned to the Company Agent, one set of `source_indexes` and one `effort`.

## Stream live progress

Send `Accept: text/event-stream` on dispatch to stream the run over Server-Sent Events instead of polling. The stream carries `RetrievalAgentStreamEnvelope` events, and the terminal `agent_result` event carries the same result you'd get from polling. See the [coding-agent reference](/documentation/integrating-tako/agent/for-coding-agent#stream-live-progress-sse) for the event taxonomy and resume semantics.

> [!NOTE]
>
> The Python and TypeScript SDKs don't have a Company Agent method yet. Call the endpoint over HTTP until they do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.