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

# Credits and Usage in The Hog

> The Hog charges credits for API calls that fetch, enrich, scrape, or research data.

Credits are the unit of consumption in The Hog. They're charged when an API call performs paid work to fulfil your request. Not every call costs credits — lightweight operations like health checks and polling run for free — but anything that fetches, enriches, scrapes, or researches data from external sources will draw from your credit balance.

## What costs credits

| Operation                          | Credit behaviour                                     |
| ---------------------------------- | ---------------------------------------------------- |
| `POST /api/v1/companies/search`    | Charged based on the companies searched and enriched |
| `POST /api/enrichments`            | Charged per enrichment lookup attempt                |
| `POST /api/v1/platform/scrapers/*` | Charged per scrape request                           |
| `POST /api/deep-research`          | Charged for LLM-powered deep research                |

## What is free

| Operation                 | Why it's free                               |
| ------------------------- | ------------------------------------------- |
| `GET /api/health`         | Infrastructure probe — no external calls    |
| `GET /api/operations/:id` | Polling — reads stored operation state only |

## Metered charges

Launch endpoints charge based on the work completed for your request. Responses expose customer-safe credit fields such as `creditsCharged`, estimates, and request metadata.

## Credit metering in company search responses

Company search responses include a `metering` object so you know exactly what was charged:

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [...],
  "metering": {
    "creditsCharged": 3,
    "estimatedMaxCredits": 5
  },
  "meta": {
    "requestId": "req_aabbccdd",
    "cost": { "estimated": 5, "actual": 3 }
  }
}
```

`creditsCharged` reflects what was actually deducted. `estimatedMaxCredits` is the ceiling that was reserved at the start of the call — you're only charged the actual amount.

## Insufficient credits — 402 error

If your account doesn't have enough credits to cover an operation, the API returns a `402 Payment Required` response before any external calls are made:

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Insufficient credits: 8 required, 3 available",
  "path": "/api/enrichments",
  "requestId": "req_nofunds",
  "timestamp": "2026-05-06T10:00:00.000Z"
}
```

No credits are deducted when a `402` is returned. Reduce the request scope or add credits before retrying.