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

# Enrich companies

> Trigger AI enrichment, track its progress, and enrich records in bulk.

Enrichment fills in what you don't already know — firmographics, financials, headcount, and signals — by combining AI with data providers. This guide is the task-oriented companion to the [enrichment concept](/concepts/enrichment): how to trigger it, know when it's done, and run it across many records.

## Trigger enrichment for one company

Enrichment runs asynchronously. Triggering it returns immediately; the enriched values appear on the record once processing completes.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.metal.ai/v1/companies/665f1c2a9b1e4a0012a3b4c5/enrich \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
```

<Info>
  Create a company with at least a `canonicalName` — and a `website` when you have one — before enriching. The more identifying detail you provide, the more accurate the result.
</Info>

## Know when enrichment is done

Don't hold a request open waiting for results. Instead, poll the company and compare two timestamps:

| Field                     | Meaning                                          |
| ------------------------- | ------------------------------------------------ |
| `lastEnrichmentStartedAt` | When the most recent run began.                  |
| `lastEnrichedAt`          | When enrichment last completed and wrote values. |

A run is still in progress while `lastEnrichmentStartedAt` is newer than `lastEnrichedAt`.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import time
import requests

BASE = "https://api.metal.ai/v1"
headers = {
    "x-metal-client-id": os.environ["METAL_CLIENT_ID"],
    "x-metal-api-key": os.environ["METAL_API_KEY"],
}

def wait_for_enrichment(company_id, timeout=300, interval=10):
    requests.post(f"{BASE}/companies/{company_id}/enrich", headers=headers)
    deadline = time.time() + timeout
    while time.time() < deadline:
        company = requests.get(f"{BASE}/companies/{company_id}", headers=headers).json()["data"]
        started = company.get("lastEnrichmentStartedAt")
        finished = company.get("lastEnrichedAt")
        if finished and (not started or finished >= started):
            return company
        time.sleep(interval)
    raise TimeoutError(f"Enrichment for {company_id} did not finish in {timeout}s")
```

<Tip>
  Prefer not to poll? Configure a [webhook](/guides/webhooks) trigger so Metal notifies your system when enrichment completes.
</Tip>

## Enrich in bulk

Looping `enrich` one company at a time works, but it's slow and burns through [rate limits](/guides/rate-limits). To enrich many records efficiently, add them to a [list](/guides/manage-lists) and enrich at the list level — Metal computes enriched columns across every entry.

<Steps>
  <Step title="Collect the records">
    Add the companies you want to enrich to a list.
  </Step>

  <Step title="Enrich the list">
    Trigger enrichment at the list level so it fans out across all entries.
  </Step>

  <Step title="Read results">
    Read the list entries to pull enriched values for every company at once.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Build a list" icon="list" href="/guides/manage-lists">
    Group records to enrich and analyze them in bulk.
  </Card>

  <Card title="Automate it" icon="robot" href="/guides/automate-workflows">
    Run a workflow that enriches and screens targets end to end.
  </Card>
</CardGroup>