Skip to main content

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 are the unit of consumption in The Hog. They’re charged when an API call reaches out to external data providers to fulfil your request. Not every call costs credits — lightweight operations like health checks and polling run for free — but anything that fetches, enriches, or generates data from external sources will draw from your credit balance.

​
What costs credits

OperationCredit behaviour
POST /api/companies/searchCharged per unique domain where an external provider is consulted
POST /api/people/enrichCharged per provider attempt in the enrichment waterfall
POST /api/generateCharged for content generation
POST /api/deep-researchCharged for LLM-powered deep research

​
What is free

OperationWhy it’s free
GET /api/healthInfrastructure probe — no external calls
GET /api/operations/:idPolling — reads internal state only
POST .../estimatePre-flight check — no external calls, no data returned

​
Pre-flight estimates

Always call the /estimate endpoint before running an expensive operation. Estimates are free and don’t consume credits. They tell you the projected cost, whether the call will be synchronous or asynchronous, and whether your current plan can cover it — before you commit.
Send the same body you’d send to the real endpoint, but route it to the /estimate path: 
curl -X POST https://api.thehog.ai/api/people/enrich/estimate \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      { "platform": "linkedin", "username": "jane-doe-example" }
    ],
    "maxEmailProviderAttempts": 2,
    "maxPhoneProviderAttempts": 3
  }'
The estimate response looks like this: 
{
  "data": {
    "estimatedCredits": 5,
    "likelySyncOrAsync": "sync",
    "expectedLatencyRange": "2–8s",
    "providersLikelyUsed": ["provider-a", "provider-b"],
    "withinPlanLimits": true
  },
  "meta": {
    "requestId": "req_est_9988",
    "projectId": "proj_abc123"
  }
}
FieldDescription
estimatedCreditsHow many credits the real call is expected to consume
likelySyncOrAsyncWhether the real call will return 200 or 202
expectedLatencyRangeApproximate wall-clock time for the operation
providersLikelyUsedWhich external providers are likely to be queried
withinPlanLimitsWhether your current plan can cover the estimated cost

​
Credit metering in company search responses

Company search responses include a metering object so you know exactly what was charged: 
{
  "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: 
{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Insufficient credits: 8 required, 3 available",
  "path": "/api/people/enrich",
  "requestId": "req_nofunds",
  "timestamp": "2026-05-06T10:00:00.000Z"
}
No credits are deducted when a 402 is returned. Run the /estimate endpoint first to confirm withinPlanLimits is true before submitting the real call.

​
Optimizing credit usage

​
Limit enrichment waterfall depth

People enrichment tries multiple providers in sequence until it finds a result. You can cap how deep it goes to reduce credit consumption: 
curl -X POST https://api.thehog.ai/api/people/enrich \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "identities": [
      { "platform": "linkedin", "username": "jane-doe-example" }
    ],
    "maxEmailProviderAttempts": 2,
    "maxPhoneProviderAttempts": 1
  }'
Setting maxEmailProviderAttempts: 1 means The Hog will try only the top-ranked email provider and stop, regardless of whether a result was found. This costs fewer credits at the expense of lower coverage.
For bulk enrichment jobs, run a small sample first with maxEmailProviderAttempts: 1 to establish your hit rate. If coverage is acceptable, you avoid paying for deeper provider waterfalls across your entire list.
Setting maxEmailProviderAttempts to 1 means The Hog tries only a single provider for email. If that provider returns no result, no further attempts are made. The same applies to maxPhoneProviderAttempts. Lower depth reduces cost but also reduces coverage.