> ## 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.

# Sync and Async Operations in The Hog

> Fast API calls return 200 immediately. Long-running tasks return 202 with a poll URL. Learn when each pattern applies and how to poll for results.

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           |

<Tabs>
  <Tab title="Sync response (200)">
    Data is available immediately in the `data` field.

    ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "data": [
        {
          "id": "comp_xyz789",
          "name": "Acme Corp",
          "industry": "Software",
          "employee_count": 220,
          "is_hiring": true
        }
      ],
      "meta": {
        "requestId": "req_aabbccdd"
      }
    }
    ```
  </Tab>

  <Tab title="Async accepted (202)">
    The response contains an operation ID and a URL to poll. No result data yet.

    ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
    "id": "op_99887766",
    "operationId": "op_99887766",
    "status": "queued",
    "pollUrl": "/api/operations/op_99887766",
    "meta": {
    "requestId": "req_11223344"
    }
    }
    ```
  </Tab>

  <Tab title="Polling response (200)">
    Call `GET /api/operations/:id` to check progress. When `status` is `succeeded`, `result` contains the full output.

    ```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      "id": "op_99887766",
      "status": "succeeded",
      "progress": 100,
      "result": {
        "email": "jane.doe@acme.com",
        "phone": "+1-555-0100",
        "emailVerified": true
      },
      "error": null
    }
    ```
  </Tab>
</Tabs>

## How to poll

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

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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               |

<Warning>
  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.
</Warning>

### Recommended polling strategy

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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:

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"]
  }'
```

<Tip>
  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.
</Tip>