# Credits and Usage

API requests consume credits from your account's yearly allocation.

## Credit Consumption by Endpoint

| Endpoint | Consumes Credits | Description |
|  --- | --- | --- |
| **Company Enrich** (`/companies/enrich`) | Yes | Credits depend on field groups requested and data returned |
| **Functional Area Intelligence** (`/companies/functional-areas`) | Yes | Credits charged based on data returned |
| **Company Hierarchy** (`/companies/hierarchy`) | Yes | Credits charged based on data returned |
| **Intent Signals** (`/intent/enrich`) | Yes | Credits charged per record returned, across `topics` and `activities` sections. Use `fields: ["summary"]` for a free overview before drilling in. |
| **AI Maturity** (`/companies/enrich` with `ai_maturity`) | Yes | Credits charged based on data returned |
| **Contracts in Enrich** (`/companies/enrich` with `contracts`) | Yes | Credits charged based on data returned |
| **Contract Search** (`/contracts/search`) | Yes | Credits charged per contract record returned |
| **Contract Search Estimate** (`/contracts/search/estimate`) | No | Preview credit cost without consuming credits or returning data |
| **Contact Enrich** (`/contacts/enrich`) | Yes | Credits charged per contact record returned |
| **Contact Enrich Estimate** (`/contacts/enrich/estimate`) | No | Preview credit cost without consuming credits or returning data |
| **Contact Search** (`/contacts/search`) | No | Find contacts by company, job function, seniority, location, and time in role |
| **Enrich Estimate** (`/companies/enrich/estimate`) | No | Preview credit cost without consuming credits or returning data |
| **FAI Estimate** (`/companies/functional-areas/estimate`) | No | Preview credit cost without consuming credits or returning data |
| **Hierarchy Estimate** (`/companies/hierarchy/estimate`) | No | Preview credit cost without consuming credits or returning data |
| **Intent Estimate** (`/intent/enrich/estimate`) | No | Preview credit cost without consuming credits or returning data. Returns per-section breakdown (`topics` vs `activities`). |
| **Company Search** (`/companies/search`) | No | Discover companies by filter; requires positive balance. Results capped at 25,000 per query — use filters to segment. |
| **Company Match** (`/companies/match`) | No | Resolve companies by name, domain, or country |
| **Catalog** (`/catalog/`*) | No | Browse vendors, products, categories, and taxonomy data |
| **Credits** (`/credits`) | No | Check your current credit balance |


Endpoints that don't consume credits still require a positive balance on your account. Contact your account manager for details on credit pricing.

## How credits work

Credits are based on **what data is returned** — the field groups you request and how much data is found.

Credits are only charged the first time you enrich a company record within your 12-month contract period. Re-enriching the same company within that contract window is free.

**Example:** You enrich `acme.com` in January — credits are charged. You enrich `acme.com` again in July to get fresh data — no credits charged. After your contract renews, the next enrichment of `acme.com` counts again.

Contact your account manager for pricing details.

## Estimating Cost Before You Call

`POST /data-api/v2/companies/enrich/estimate` returns the credit cost of an enrichment request without consuming credits or returning data. Useful before large batch jobs or when budgeting field groups.

Send the same request body you would send to `/companies/enrich`:

```bash
curl -X POST https://api.hginsights.com/data-api/v2/companies/enrich/estimate \
  -H "Authorization: Bearer $HG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "field_groups": ["firmographics", "technographics"]
  }'
```

```json
{
  "credits_estimate": 12,
  "available_credits": 65750,
  "sufficient_credits": true,
  "details": {
    "firmographics": { ... },
    "technographics": { ... }
  }
}
```

| Field | Description |
|  --- | --- |
| `credits_estimate` | Maximum credits the matching `/enrich` call would consume |
| `available_credits` | Credits remaining in your current cycle |
| `sufficient_credits` | Whether your balance covers the estimate |
| `details` | Per-field-group breakdown for the requested data types |


The estimate is an upper bound — actual `/enrich` charges can be lower if less data is returned, or zero if the company was already enriched within your contract period.

## Checking Your Balance

### Via Credits API

Monitor your balance programmatically — useful for pre-checking before large batch jobs, automated alerts when your balance is low, or pulling credit data into your own reporting tools.

```bash
curl https://api.hginsights.com/data-api/v2/credits \
  -H "Authorization: Bearer $HG_API_KEY"
```

```json
{
  "credits": {
    "total": 100000,
    "used": 34250,
    "remaining": 65750
  }
}
```

### Via Credit Dashboard

If you have access to the [HG Admin Portal](https://admin.hginsights.com), go to **Settings** > **Credits Usage** to see your balance, usage history, and request more credits. Not all accounts have dashboard access — contact your account manager to get it enabled.

## Need More Credits?

From the Credit Dashboard, click **Request more credits**, or reach out directly to your account manager.