Sync and Async Operations in The Hog

The Hog uses two response patterns depending on how long an operation takes. Fast operations return data immediately in the response body with a 200 status. Operations that require more processing time — like enriching large contact lists or running deep research — return a 202 Accepted response with an operation ID you can poll until the work is done. Knowing which pattern to expect helps you design your integration correctly from the start.

Sync operations (200)

These calls complete quickly and return data directly in the response. You don’t need to do anything after the initial request.

Async operations (202)

These calls kick off background work and return immediately with a poll URL. You retrieve the result by polling GET /api/operations/:id until the status reaches succeeded or failed.

Endpoint	Async trigger
`POST /api/v1/companies/search`	Always async — company discovery
`POST /api/v1/people/search`	Always async — people discovery
`POST /api/enrichments`	Batch enrichments and signal enrichments
`POST /api/v1/search`	Search jobs submitted for background processing
`POST /api/deep-research`	Always async — LLM-powered deep research
`POST /api/v1/platform/scrapers/web/crawl`	Website crawl jobs
`POST /api/v1/platform/scrapers/web/scrape/batch`	Multiple page scrapes
`POST /api/v1/platform/scrapers/web/scrape/jobs`	Deep scrape for long or dynamic pages

Sync response (200)
Async accepted (202)
Polling response (200)

Data is available immediately in the data field.

{
  "data": [
    {
      "id": "comp_xyz789",
      "name": "Acme Corp",
      "industry": "Software",
      "employee_count": 220,
      "is_hiring": true
    }
  ],
  "meta": {
    "requestId": "req_aabbccdd"
  }
}

The response contains an operation ID and a URL to poll. No result data yet.

{
"id": "op_99887766",
"operationId": "op_99887766",
"status": "queued",
"pollUrl": "/api/operations/op_99887766",
"meta": {
"requestId": "req_11223344"
}
}

Call GET /api/operations/:id to check progress. When status is succeeded, result contains the full output.

{
  "id": "op_99887766",
  "status": "succeeded",
  "progress": 100,
  "result": {
    "email": "jane.doe@acme.com",
    "phone": "+1-555-0100",
    "emailVerified": true
  },
  "error": null
}

How to poll

Once you have an operationId, call GET /api/operations/:id on a schedule until the status is terminal.

curl https://developer.thehog.ai/api/operations/op_99887766 \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"

Operation status values

Status	Meaning
`queued`	Work is waiting to start
`processing`	Work is in progress — check `progress` for a 0–100 estimate
`succeeded`	Work is complete — read the `result` field
`failed`	Work failed — read the `error` field for details
`partial_success`	Some results were returned; check both `result` and `error`
`cancelled`	The operation was cancelled before completion

Don’t poll more aggressively than once per second. The operations endpoint has a dedicated rate limit. If you exceed it, you’ll receive a 429 response.

Recommended polling strategy

# Simple polling loop — wait 2 seconds between checks
while true; do
  RESPONSE=$(curl -s https://developer.thehog.ai/api/operations/op_99887766 \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx")
  STATUS=$(echo $RESPONSE | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
    echo $RESPONSE | jq '.result // .error'
    break
  fi
  sleep 2
done

Estimate responses include:

{
  "data": {
    "estimatedCredits": 5,
    "likelySyncOrAsync": "async",
    "expectedLatencyRange": "10–30s",
    "expectedLookupDepth": 2,
    "withinPlanLimits": true
  },
  "meta": {
    "requestId": "req_estimate001"
  }
}

Idempotency

For async POST requests, you can supply an Idempotency-Key header. If you retry the same request with the same key within the idempotency window, the API returns the original response rather than creating a duplicate operation. This example uses a batch enrichment request, which is always asynchronous.

curl -X POST https://developer.thehog.ai/api/enrichments \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: enrich-jane-doe-20260506" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      { "linkedin_url": "https://www.linkedin.com/in/jane-doe-example" },
      { "email": "jane@example.com" }
    ],
    "fields": ["contact.email", "contact.phone"]
  }'

Use a deterministic idempotency key — such as a hash of the request payload or a stable record ID — so that retries after a network failure are safe and don’t double-charge credits.

Get Started

Core Concepts

Guides

Reference

Sync and Async Operations in The Hog

Sync operations (200)

Async operations (202)

How to poll

Operation status values

Recommended polling strategy

Idempotency

​Sync operations (200)

​Async operations (202)

​How to poll

​Operation status values

​Recommended polling strategy

​Idempotency

Sync operations (200)

Async operations (202)

How to poll

Operation status values

Recommended polling strategy

Idempotency