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.

Every response from The Hog API wraps its payload in a consistent envelope so you can parse results, track costs, and correlate requests in a uniform way — regardless of which endpoint you call. This page describes each envelope shape, the fields you can expect, and how to read cost and request metadata.

​
The X-Request-Id header

Every authenticated response includes an X-Request-Id HTTP header containing a UUID that uniquely identifies the request. This value is also mirrored inside the response body as meta.requestId. Save it when you contact support — it lets the team locate the exact request in logs instantly. 
# Example response header
X-Request-Id: 3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a

​
Sync response (HTTP 200)

Fast operations — company search, people search, context assembly, signals — complete within the request lifecycle and return HTTP 200. The data field holds the endpoint-specific payload. 
// HTTP 200 — synchronous result
{
  "data": {
    // endpoint-specific payload, e.g. an array of companies or a context object
  },
  "meta": {
    "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a",
    "projectId": "proj_01HZ9K2QW3RV4M5N6P7Q8R9S0T", // present when you sent X-Project-Id
    "cost": {
      "estimated": 5,   // credits estimated before execution
      "actual": 4       // credits actually consumed
    }
  }
}
meta.projectId is only present when you included the X-Project-Id request header. Omit the header and the field is absent from the response.

​
Cost fields

FieldTypeDescription
meta.cost.estimatedintegerCredits estimated before the operation ran
meta.cost.actualintegerCredits actually deducted from your balance
The two values may differ slightly — estimates are computed before provider calls complete. Your balance is always charged the actual amount.

​
Async accepted response (HTTP 202)

Long-running operations — enrichment with asyncPreferred: true, content generation for complex prompts, and deep research — are accepted immediately and processed in the background. The response contains everything you need to poll for the result. 
// HTTP 202 — async job accepted
{
  "operationId": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "queued",
  "pollUrl": "https://api.thehog.ai/api/operations/op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "meta": {
    "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a",
    "estimatedCost": 20 // estimated credits for this async job
  }
}
FieldTypeDescription
operationIdstringUnique ID for the background job
statusstringAlways "queued" on acceptance
pollUrlstringFully-qualified URL to poll for status and result
meta.requestIdstringCorrelates to the X-Request-Id header
meta.estimatedCostintegerEstimated credits the job will consume
Use pollUrl directly in subsequent GET requests. See Operation status response below for the shape returned while polling.

​
Estimate response

Before running an enrichment, generation, or research job, call the corresponding /estimate endpoint to get a cost and latency preview without consuming any credits. 
// Estimate response — no credits consumed
{
  "data": {
    "estimatedCredits": 15,
    "likelySyncOrAsync": "async",           // "sync" or "async"
    "expectedLatencyRange": "8s – 25s",     // present for most endpoints
    "withinPlanLimits": true                // false if job would exceed your plan
  },
  "meta": {
    "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a",
    "projectId": "proj_01HZ9K2QW3RV4M5N6P7Q8R9S0T"
  }
}
FieldTypeDescription
data.estimatedCreditsintegerPredicted credit cost for the actual request
data.likelySyncOrAsyncstringWhether the real call will return 200 or 202
data.expectedLatencyRangestringHuman-readable latency estimate (may be absent)
data.withinPlanLimitsbooleanfalse means the job would be blocked by your plan
Check withinPlanLimits before submitting expensive jobs. If it’s false, the actual request will be rejected with HTTP 402.

​
Operation status response (GET /api/operations/:id)

Poll this endpoint after receiving a 202 to check progress and retrieve the result when the job finishes. 
// In-progress operation
{
  "id": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "processing",
  "progress": 45,   // 0–100, or null when not yet tracked
  "result": null,   // null until status is "succeeded"
  "error": null     // null unless status is "failed"
}

// Completed operation
{
  "id": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "succeeded",
  "progress": 100,
  "result": {
    // endpoint-specific result payload
  },
  "error": null
}

// Failed operation
{
  "id": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "failed",
  "progress": null,
  "result": null,
  "error": {
    "message": "Provider returned no results for the given input."
  }
}

​
Operation statuses

queued

The job has been accepted and is waiting for a worker to pick it up.

processing

A worker is actively running the job. Check progress (0–100) for completion percentage.

succeeded

The job finished successfully. Read the result from the result field.

failed

The job encountered an unrecoverable error. Details are in the error field.

partial_success

The job completed but some sub-tasks did not succeed. result contains whatever was produced.

cancelled

The job was cancelled before it completed.
FieldTypeDescription
idstringOperation ID matching the operationId from the 202 response
statusstringCurrent status (see table above)
progressinteger | nullCompletion percentage (0–100), or null if not yet tracked
resultobject | nullResult payload when status is "succeeded" or "partial_success"
errorobject | nullError detail when status is "failed"